wkhtmltopdf Cuts Off Page Content: How to Fix Page Breaks

If wkhtmltopdf splits a line, table row, or image across pages, the cause may be its WebKit-based pagination: it lays out content as one long page and then cuts that page into sheets. CSS break rules can help in some builds, but they are not a universal fix. If text is missing at the right edge, diagnose width and horizontal overflow instead; that is a different problem.

Start by reproducing the conversion with the exact HTML, assets, wkhtmltopdf binary, and options used in production. Record the version and build, then change one variable at a time. The project documents this pagination limitation and says page-break-inside can remedy it somewhat when using the patched-Qt version; it does not promise perfect page breaks. wkhtmltopdf usage documentation

1. Identify what is being cut off

Symptom	Likely area to investigate
A line or paragraph is divided between two pages	Vertical pagination and break rules
A table row or image is split at the page boundary	Pagination, element height, and whether the block can fit on one page
Text or a table is cut off at the right edge	Content width, wrapping, margins, overflow, viewport, or scaling
Content is absent altogether	Check whether scripts, fonts, images, and other assets finished loading before conversion
Body content collides with a header or footer	Top and bottom margins and header/footer spacing

These symptoms can look similar in the resulting PDF, but they need different checks. A reported bottom-of-page split and a separate report of right-edge truncation illustrate the distinction; neither issue report establishes a universal fix. Issue #5139 · Issue #4080

2. Reproduce the exact conversion

1. Save the exact input HTML and all assets it references. If the page depends on remote assets, note that too.
2. Run the same binary outside your application wrapper with the same command-line options.
3. Record wkhtmltopdf --version, the operating system, how the binary was installed, page size, margins, media mode, and smart-shrinking setting.
4. Compare the output from a minimal input with the output from the original document. Add sections or styles back until the symptom returns.

wkhtmltopdf --version
wkhtmltopdf input.html output.pdf

Build details matter. The project documentation describes wkhtmltopdf 0.12.6 with patched Qt. Do not assume another package or build has identical behavior. In particular, verify whether your binary uses patched Qt before relying on the documented CSS page-break remedy.

3. Give the renderer cleaner places to break

Prefer natural page boundaries between sections, paragraphs, and other independent blocks. Avoid layouts composed of many separately positioned pieces that must line up across a page. WebKit pagination can split lines or images when it cuts the long rendered page into paper pages, even when the HTML looks fine in a browser.

For blocks that should stay together, try page-break-inside: avoid in the actual wkhtmltopdf build you deploy. For example:

<style>
  .keep-together {
    page-break-inside: avoid;
  }

  .report-section {
    page-break-before: auto;
    page-break-after: auto;
  }
</style>

<div class="keep-together">
  <h2>Summary</h2>
  <p>Keep this short block together where possible.</p>
</div>

Apply the rule selectively. If a block is taller than the space available on the page—or taller than a full page—the renderer cannot keep it intact there. It may move the block or still split it. Treat the rule as a request to test, not a guarantee.

4. Check page size, orientation, and margins

Page geometry controls the space available to the document and can change both wrapping and pagination. The documented default paper size is A4. Check the page size and all four margins against the design, then confirm the PDF output uses the intended settings.

wkhtmltopdf \
  --page-size A4 \
  --orientation Portrait \
  --margin-top 15mm \
  --margin-bottom 15mm \
  --margin-left 12mm \
  --margin-right 12mm \
  input.html output.pdf

Use --page-width and --page-height when you need explicit dimensions instead of a named paper size. If content is clipped at the right edge, check whether the content width plus horizontal margins exceeds the printable page width. Also inspect fixed-width elements, non-wrapping text, wide tables, and overflow styles.

5. Compare smart shrinking as a separate variable

Smart shrinking is enabled by default in the documented options. The manual describes --disable-smart-shrinking as disabling WebKit’s strategy for changing the pixel-to-DPI ratio. It is a layout-scaling control, not a documented general fix for page breaks.

# Baseline: default smart shrinking
wkhtmltopdf input.html baseline.pdf

# Controlled comparison
wkhtmltopdf --disable-smart-shrinking input.html no-shrinking.pdf

Compare page count, text size, wrapping, and edge clipping in both files. A change can affect overall scale and line wrapping, so it may improve one symptom while changing another. Issue reports include configurations with smart shrinking disabled and clipping symptoms, which is another reason not to treat the flag as a guaranteed remedy.

6. Confirm the media mode and print styles

By default, a conversion may render differently from the browser view you inspected. The --print-media-type option tells wkhtmltopdf to use print styles rather than screen styles. If your page-break rules or sizing adjustments are inside @media print, enable print media and make sure those rules and their assets are actually present in the converted document.

@media print {
  .keep-together {
    page-break-inside: avoid;
  }

  .screen-only {
    display: none;
  }
}

wkhtmltopdf --print-media-type input.html print.pdf

Compare the conversion with and without print media if the result does not match your browser preview. Keep in mind that changing media mode can alter layout, visibility, and dimensions throughout the document.

7. Wait for JavaScript-generated content and assets

JavaScript is enabled by default in the documented options, with a default JavaScript delay of 200 milliseconds. That may be too short for a page that renders data, images, or layout asynchronously. A wait option can solve missing or unfinished content; it does not repair the underlying page-breaking algorithm.

# Wait a set amount of time after load
wkhtmltopdf --javascript-delay 1000 input.html delayed.pdf

# Wait for the page to set a specific status
wkhtmltopdf --window-status ready input.html ready.pdf

For the second example, your page must set window.status to ready when the content is ready. The manual also documents --run-script for running an additional script after page load. Choose a deliberate wait condition rather than increasing the delay blindly.

8. Account for headers and footers

If clipping or overlap appears only near the top or bottom of a page, check the header and footer configuration together with the top and bottom margins. The margins determine the body area available on the page; header and footer spacing also needs room. A reported issue included headers and footers, but did not confirm that they caused the split, so verify this in your own reproduction.

9. Troubleshooting checklist

What you see	What to check	Next step
Text line cut between pages	Build, pagination, content grouping	Try selective page-break-inside: avoid on a short block; verify patched Qt.
Large block still splits	Whether the block fits in the available page area	Shorten or divide it at a natural boundary; an oversized block cannot be kept intact on one page.
Right edge truncates	Page width, margins, fixed widths, overflow, long unbroken strings, scale	Reduce content width or adjust geometry; test smart shrinking separately.
Content differs from browser preview	Print versus screen media styles	Try --print-media-type and inspect the print-specific CSS and assets.
Dynamic content is missing	JavaScript completion and asset loading	Use a suitable JavaScript delay, window status, or post-load script.
Only content near the page edge is affected	Margins and header/footer spacing	Increase available body space or adjust the header/footer layout.
A suggested flag has no effect	Exact binary version, build, and whether the option applies to the symptom	Reproduce with the deployed binary; do not infer that a setting fixes all builds.

10. Improve repeatability, performance, and cost

For reliable output, keep the input HTML and assets fixed while investigating, record the full command and binary version, and change only one setting per comparison. Once a change helps, repeat the conversion in the deployment environment and inspect several pages, including boundaries around large blocks and wide tables.

Wait only as long as the page needs to finish rendering. Longer JavaScript delays can increase conversion time, and they do not make pagination more accurate. Large images, complex layouts, and remote assets can also affect conversion time; the cited project documentation does not provide comparative performance or cost figures, so measure those in your own workload. wkhtmltopdf is a self-hosted command-line tool; its runtime and infrastructure costs depend on how and where you run it.

Or skip the browser setup

If your job is to capture a clean webpage as an image or PDF, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners are accepted and removed, along with known newsletter popups and chat widgets, before the shot.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status.
• An MCP server lets AI agents use screenshot tools, including from Claude, Cursor, or another MCP client.
• The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Sign up for 1,000 free screenshots a month, with no card.

FAQ

Does page-break-inside: avoid work in every wkhtmltopdf build?

No. The project documents it as a partial remedy for the patched-Qt version. Confirm your build and test the actual content.

Is a split line proof that the HTML source is missing text?

No. The renderer may have split the rendered page at a page boundary. Inspect the PDF and reproduce the conversion before changing the source content.

Will disabling smart shrinking fix page breaks?

There is no documented guarantee. It changes the scaling strategy, so use it as a controlled comparison and check both pagination and width.

Why does the PDF differ from the browser?

The conversion can use print media styles and its own page geometry, rendering options, and timing. Compare those inputs with the browser view you used.

Sources

• wkhtmltopdf usage documentation: page breaking, page geometry, media mode, smart shrinking, and JavaScript options.
• Issue #5139: a report of bottom text splitting with wkhtmltopdf 0.12.6 on CentOS 7; no confirmed fix.
• Issue #4080: a report of right-side truncation, a distinct symptom from vertical page splitting.