Set an explicit top margin, then tune header spacing to the header’s actual rendered height. A practical diagnostic command is wkhtmltopdf --margin-top 25mm --header-spacing 5 input.html output.pdf. The values are only a starting point: inspect the PDF and adjust them for your header, paper size, fonts and page breaks. If a footer is involved, set and tune the bottom margin separately.
Why wkhtmltopdf clips or moves header content
wkhtmltopdf lays out the body, header and footer within a page geometry controlled by margins and spacing. The header.spacing setting is the gap between the header and the document content. The project’s settings documentation warns that an excessive value can place the header outside the PDF; its stated correction is to adjust margin.top.
That means two symptoms that look similar may have different causes:
- Body text is covered: the top margin does not reserve enough room for the rendered header.
- Unexpected white space appears: the margin or spacing is larger than the header requires.
- The header is outside the page: header spacing is too large for the available page geometry, or the header is being positioned relative to a margin you did not account for.
- The header and body move together: some layouts couple the top margin to both positions, so changing the margin cannot independently move only one element.
Header HTML height is not necessarily the height you see in the source file. Font substitution, images, line wrapping, CSS margins and the selected paper size all change the rendered height.
#1 Best Overall
- BEST FOR SMALL BUSINESSES – Engineered for extraordinary productivity, the Brother DCP-L2640DW Monochrome (Black & White) 3-in-1 combines laser printer, scanner, copier in one compact footprint and delivers high-quality black & white prints
- FAST PRINTER WITH EFFICIENT SCANNING – Produces documents quickly with print speeds up to 36 ppm(2) and scan speeds up to 23.6/7.9 ipm(3) (black/color). A 50-page auto document feeder(4) allows for convenient, time saving multi-page scanning and copying
- FLEXIBLE CONNECTION OPTIONS – Easily navigate the changing demands of your business with secure multi-device connectivity via built-in dual-band wireless (2.4GHz / 5GHz) and Ethernet. Or connect locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Print, scan, and manage your wireless printer anytime, from almost anywhere from your mobile device. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(5)
- CHOOSE BROTHER GENUINE TONER – When it’s time to replace your toner, be sure to choose Brother Genuine TN830 or TN830XL replacement toner. And with Refresh EZ Print Subscription Service, you’ll never worry about running out of toner again and you’ll enjoy savings of up to 50%(6) on Brother Genuine Toner. Get started with Refresh today with a Free Trial(1)
Use a controlled test before changing production templates
- Record the renderer. Run
wkhtmltopdf --versionand note the operating system and whether the binary is a patched-Qt build. Reported behavior is version- and build-specific; one issue concerns version 0.12.5 with patched Qt on Ubuntu 16.04.5. - Create a baseline. Render the document without header and footer options. Save this PDF so you can compare the body’s natural starting position and page breaks.
- Add only the header. Run the same input with
--header-html(or the plain-text header options). Determine whether the body is covered, the header is off-page, or only excessive space is present. - Set both controls explicitly. Add
--margin-topand--header-spacing, changing one value at a time. Inspect the generated PDF after each change. - Test the footer separately. If the problem appears only with
--footer-html, compare PDFs with and without that option and set--margin-bottomand footer spacing explicitly.
Command-line fix
Start with explicit top geometry
Use this as a diagnostic starting point:
wkhtmltopdf --margin-top 25mm --header-spacing 5 input.html output.pdf25mm reserves space above the body; 5 is the header-to-content gap in the renderer’s spacing units. Neither number is a universal prescription. If the header still overlaps the body, increase the top margin or reduce the header’s rendered height. If the PDF has excessive blank space, reduce the margin or spacing while checking that the body remains clear.
Header HTML and footer HTML
A complete invocation might look like this:
wkhtmltopdf
--page-size A4
--margin-top 25mm
--margin-bottom 20mm
--header-html header.html
--header-spacing 5
--footer-html footer.html
--footer-spacing 4
input.html output.pdfKeep the header and footer files small while diagnosing. Remove decorative images, unusual CSS and external dependencies temporarily. Once geometry is correct, restore them one at a time; a new line wrap or image height can require a different margin.
Plain-text headers
If you use --header-left, --header-center or --header-right, the same top-margin rule applies. These headers are usually easier to measure than HTML headers, but font size and font availability still affect their height.
How to choose margin and spacing values
Measure the header, reserve the body area
First determine the maximum rendered header height on the widest and narrowest pages. Reserve that height in --margin-top, then use --header-spacing only for the intentional gap. A header that wraps from one line to two on a narrower page needs the larger reservation.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #2
- BEST FOR HOMES & HOME OFFICES – Engineered for consistent, premium print quality, the Brother HL-L2405W Monochrome (Black & White) Laser Printer delivers sharp, crisp prints at an affordable price. Prints one-sided documents at speeds up to 30ppm(2)
- COMPACT, CONNECTED PRINTER – Flexible connection options make this an ideal printer for home use and at-home offices. Securely connect to multiple devices with built-in dual-band wireless (2.4GHz/5GHz) or locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Manage your printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Enjoy seamless, reliable everyday printing with the 250-sheet paper tray(4) and a manual feed slot that enables printing on envelopes and specialty pape
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
Account for paper size and orientation
A4, Letter, landscape mode and custom page sizes change available width, which can change line wrapping and therefore header height. Test the exact --page-size, --orientation and margins used in production rather than tuning on a different paper format.
Do not treat spacing as a substitute for margin
Spacing controls the distance between header and content; it does not reliably create all the body clearance your header needs. The official settings guidance specifically connects excessive spacing with a header being printed outside the PDF and points to margin.top as the adjustment.
When the header must sit near the top edge
Some reported layouts move the header and body together when the top margin changes. In that situation, preserve enough top margin for the body, then design the header within that available area. Do not assume that the header can always be positioned independently above the body margin; verify the actual PDF.
Wrapper-library equivalents
Libraries expose the same concepts under different names. Set the equivalent of:
Rank #3
- FAST PRINT SPEEDS: Print up to 19 pages per minute.
- COMPACT DESIGN: Space-saving, compact design fits anywhere in your home, school or small office.
- WIRELESS CONNECTIVITY: Print from almost anywhere in your workspace using your compatible mobile device.
- PAPER CAPACITY: Up to 150 sheets.
- SUSTAINABILITY: Uses less than 2 watts in Energy Saver mode.
margin.topormarginTopfor body clearance.header.spacingorheaderSpacingfor the gap between header and content.header.htmlUrl,headerHtmlor the library’s HTML-header field for the header document.margin.bottomand footer spacing when a footer is enabled.
Confirm the wrapper’s generated command line when possible. A wrapper may apply defaults or omit a margin when only a footer option is supplied, making the underlying problem look unrelated to your code.
Footer-only and version-specific failures
An issue report for wkhtmltopdf 0.12.5 with patched Qt describes a footer-only configuration that removed the top margin and moved content upward. Treat that as a reported configuration, not a universal rule. Compare these runs:
wkhtmltopdf input.html no-footer.pdf
wkhtmltopdf --footer-html footer.html input.html with-footer.pdf
wkhtmltopdf --margin-top 25mm --margin-bottom 20mm --footer-html footer.html input.html explicit-margins.pdfIf only the second file shifts, keep both vertical margins explicit and inspect the wrapper or package that assembled the command.
Troubleshooting checklist
Header overlaps the first paragraph
- Increase
--margin-topuntil the body starts below the header. - Reduce CSS top and bottom margins inside the header HTML if they are accidental.
- Check for a wrapped title or substituted font that increased header height.
Large blank area appears above the body
- Reduce
--margin-topin small increments. - Reduce
--header-spacingif the gap itself is excessive. - Ensure the header is not being rendered outside the page because spacing is too large; the documentation warns about this failure mode.
Header is missing or clipped at the top edge
- Render with a larger top margin and smaller spacing.
- Check that the header URL is reachable by the wkhtmltopdf process and that local-file access settings match your setup.
- Compare an HTML header with a plain-text header to isolate template versus geometry problems.
Only pages after the first are wrong
- Inspect page-break behavior and content that changes the header’s height.
- Check whether a page-specific CSS rule, image, or font loads only after the first page.
- Render a minimal multi-page document with the same header to distinguish content from renderer behavior.
Adding a footer moves content upward
- Compare output with and without
--footer-html. - Set
--margin-topand--margin-bottomexplicitly in the footer run. - Set footer spacing separately; do not compensate for a footer by arbitrarily changing the top margin.
Changing the margin moves the header too
That coupling has been reported in older layouts. Keep the body clearance you need, then position the header inside the resulting area. Verify each change in the PDF rather than relying on the source coordinate assumptions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #4
- BEST FOR HOME OFFICES & SMALL TEAMS – Engineered for consistent, premium print quality, the Brother HL-L2460DW Monochrome (Black & White) Laser Printer produces documents that are clear, crisp, and easy to review and share, all at an affordable price
- COMPACT, CONNECTED, EXCEPTIONALLY EFFICIENT– Connect with built-in dual-band wireless (2.4GHz/5GHz), Ethernet, or to a single computer via USB interface. Prints at speeds up to 36ppm(2), plus automatic duplex printing saves time and reduces paper waste
- BROTHER MOBILE CONNECT APP – Manage your wireless printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Tackle high-volume black & white printing with the 250-sheet capacity paper tray.(4) The manual feed slot enables printing on envelopes and specialty paper
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
Version and maintenance context
Issue #3974 describes excess whitespace and content shifts on wkhtmltopdf 0.12.5 with patched Qt on Ubuntu 16.04.5, lists milestone 0.12.7 as “Fixed,” and records manual vertical margins as a workaround. That milestone does not prove that every distribution build or every clipping symptom behaves identically. The project repository was archived and made read-only on January 2, 2023. If explicit margins and a minimal reproduction still fail, record the exact binary, Qt build, operating system and command before deciding whether continued legacy-renderer debugging is worthwhile.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual requirement is a clean image or PDF of a web page rather than a wkhtmltopdf-generated document, ScreenshotNeo makes the capture in one request. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for request options. The service supports full-page capture, CSS-selector elements, device presets, custom viewports, retina scale, PDF paper and margin controls, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, timezone and geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification. Every plan includes every feature. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.
FAQ
Is 25 mm the correct top margin for every header?
No. It is only a practical diagnostic starting value. The correct margin depends on rendered header height, paper size, fonts, wrapping and spacing.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Should I increase header spacing when content is clipped?
Usually start with the top margin. Spacing is the gap between header and content, and excessive spacing can push the header outside the PDF.
Best Value
- FROM AMERICA'S MOST TRUSTED PRINTER BRAND – Perfect for small teams printing professional-quality black & white documents and reports. Perfect for 1-3 people
- WORLD'S SMALLEST LASER IN ITS CLASS – Precision laser printing that fits anywhere
- FAST PRINT SPEEDS – Up to 21 black-and-white pages per minute single-sided
- WIRELESS WITH SELF-RESET – Helps you stay connected
- PRINT FROM ANY DEVICE – Wireless printing from any mobile device, PC or tablet. Works with Microsoft, Mac, AirPrint, Android, Chromebook and more
Does milestone 0.12.7 guarantee that my installation is fixed?
No. The milestone belongs to a specific issue report; packaged builds, platforms and other clipping causes may differ.
Why test without a footer?
A reported 0.12.5 patched-Qt configuration changed top positioning when a footer was enabled. A comparison isolates that variable.
Frequently Asked Questions
Can CSS alone reserve space for a wkhtmltopdf header?
Do not rely on body CSS alone. Reserve header clearance with the renderer’s top margin and use header spacing for the intentional gap.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →What should I include in a bug report?
Include wkhtmltopdf –version output, operating system, patched-Qt status, complete command, minimal HTML/header files and PDFs from baseline and failing runs.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
