Set the page’s reserved header area with --margin-top (or -T). Set the gap between the header and the document separately with --header-spacing. For example:
wkhtmltopdf --margin-top 20mm --header-html header.html --header-spacing 3 input.html output.pdfThe values are starting points, not universal defaults. Header height, page size, CSS, and your installed wkhtmltopdf build determine the correct settings, so inspect the generated PDF and adjust them together. See the wkhtmltopdf usage manual and the page settings reference.
What each margin option controls
Two options are commonly confused:
| Option | What it moves | Documented unit or default | When to change it |
|---|---|---|---|
--margin-top <unitreal> or -T |
Reserves space at the top of every page for the header and its surrounding area. | Use a CSS-style unit such as mm; the library setting is margin.top. |
The body starts too close to the top edge, overlaps the header, or the header needs more room. |
--header-spacing <real> |
Changes the distance between the rendered header and the document content. | Millimetres; the command-line help lists a default of 0. |
The header is correctly placed but the content-to-header gap is too small or too large. |
--header-spacing does not replace --margin-top. A large spacing value without enough top margin can place the header outside the printable page area. In that case, reduce the spacing and/or increase the top margin.
Choose a text or HTML header
Text header options
For a simple text header, use the --header-* options documented by your installed binary. wkhtmltopdf supports substitution tokens such as [page], [topage], [webpage], [title], and [doctitle]. A representative command is:
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
wkhtmltopdf --margin-top 18mm
--header-left 'Invoice [page] of [topage]'
--header-right '[date]'
input.html output.pdfToken support and exact option names can vary by build, particularly between distributions and binaries with different Qt patches. Confirm them with wkhtmltopdf --extended-help before putting them into automation.
HTML header documents
Use --header-html header.html when the header needs layout, images, tables, or CSS. The header is a separate HTML document, so style it independently from the main document. The project’s example resets the header body’s border and margin:
<body style='border:0; margin: 0;' onload='subst()'>
<table style='width:100%'>
<tr><td class='title'></td><td class='page'></td></tr>
</table>
</body>The subst() script in the project example reads values supplied to the header document and fills elements whose classes correspond to supported variables. Treat that markup as a pattern, not a guarantee that every clipping problem will disappear; the header’s actual rendered height and CSS still determine the required margin.
Set the margin step by step
- Check the binary and its options. Run
wkhtmltopdf --versionandwkhtmltopdf --extended-help. Confirm that your build accepts--header-html,--header-spacing, and the header options you plan to use. - Start with an explicit top margin. Add
--margin-topto the command. For example,--margin-top 20mmreserves 20 millimetres at the top of each page. - Add the header source. Use either a text option such as
--header-leftor an HTML file with--header-html header.html. - Set the gap separately. Add
--header-spacing 3when you need a 3 mm gap between the header and the content. Omit it or set it to0when no extra gap is required. - Render a representative document. Include a short first page and a page containing the longest expected heading, table, or image. Header height can change with real content and fonts.
- Inspect the PDF at 100%. Look at the first page, a middle page, and the final page. Increase the top margin if content collides with the header; reduce excessive spacing if the header is pushed beyond the page.
How to tune the two values
Content touches or overlaps the header
Increase --margin-top first. The top margin is the reserved page area; spacing alone does not create a reliable header region. If a visible gap is still needed after the header fits, add or increase --header-spacing in small increments.
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 →Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
The header is clipped or appears outside the page
Check for an unnecessarily large --header-spacing. Lower it, then increase --margin-top if the header itself needs more room. Also inspect the header HTML for fixed heights, large padding, borders, or images that make its rendered height larger than expected.
The first page looks correct but later pages do not
Compare pages with different content lengths and page breaks. A header that wraps on one page, loads a different image, or uses a missing font can have a different height. Keep the header layout deterministic and reserve enough top margin for its largest expected rendering.
The header has a gap but the body still starts too high
Do not compensate by adding arbitrary top padding to the main HTML. Keep page geometry in the wkhtmltopdf options: use --margin-top for reserved space and --header-spacing for the header-to-content gap. This avoids a document-specific offset that changes with page size.
Units, page geometry, and CSS details
Use an explicit unit for the top margin, such as mm, rather than relying on an ambiguous bare number. The header-spacing option is documented in millimetres and is passed as a numeric value such as 3. Your page size, orientation, printable area, and any other margins affect the remaining content area, so tune the complete command rather than one number in isolation.
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
For an HTML header, keep the header document’s body border and margin at zero when that matches your layout. Then control the external page reservation with --margin-top. Header CSS that sets large margins, transforms, absolute positions, or oversized images can still extend beyond the apparent header box.
The usage manual is maintained on the project’s master branch and is not tied to one release in the referenced page. Builds can differ, including availability of options associated with patched Qt. Always compare the installed binary’s own help output with the command you deploy.
Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
Unknown long argument --header-spacing |
The installed build does not expose that option or the command is using a different executable than expected. | Run wkhtmltopdf --version and --extended-help; install or invoke the intended build, then verify again. |
| Header text is present but body overlaps it | Top margin is too small for the rendered header. | Increase --margin-top; only then adjust --header-spacing for visual clearance. |
| Header is pushed off the page | Spacing is too large for the reserved top area, or the header HTML is taller than expected. | Reduce --header-spacing, increase --margin-top, and remove unexpected header padding or fixed height. |
| HTML header is blank | The header file cannot be loaded, has invalid markup, or depends on blocked local resources or scripts. | Use a file URL or accessible path, validate the HTML, and test the header document independently. Check the process output for load errors. |
Header variables remain literal, such as [page] |
The selected token is unsupported by that build or the token is being used in an HTML header without the required substitution script. | Check the installed manual. For an HTML header, follow the project example’s query-string substitution approach; for text headers, use only tokens listed by your binary. |
| Logo or web font changes the header height | The resource is unavailable, loads late, or falls back to a different font. | Make resources reachable to wkhtmltopdf, use stable dimensions for images, and allow enough top margin for the fallback rendering. |
| Only some pages show the header | The header command was omitted, a page-break or document mode changed behavior, or the source failed during rendering. | Reduce the case to a small multi-page document, confirm the exact command, and inspect stderr and the generated PDF page by page. |
Using the same setting through the library API
If you call libwkhtmltox instead of the command line, the equivalent top-margin setting is margin.top. Header spacing remains a separate page setting. The relationship and the warning about excessive spacing are described in the libwkhtmltox page settings reference.
Keep the values in one configuration object so command-line and library-based jobs behave consistently. Record the wkhtmltopdf version, page size, orientation, header source, top margin, and spacing with each generated PDF; that makes visual regressions easier to diagnose after an executable or CSS change.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsRank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
Or skip the browser setup
If what you actually need is a clean image or PDF of a web page rather than a locally rendered wkhtmltopdf document, ScreenshotNeo provides a website screenshot API and MCP server. Its one-call example is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for all options. Equivalent Python and Node.js requests are:
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}`);ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf tools to Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Practical checklist
- Use
--margin-topfor the reserved page area. - Use
--header-spacingonly for the header-to-content gap. - Measure the tallest real header, including images, padding, and fallback fonts.
- Inspect more than the first page of the generated PDF.
- Verify option support with the exact installed binary.
- Keep HTML-header CSS independent and reset unintended body margins.
Frequently Asked Questions
Can I set the top margin with a short option?
Yes. The short form is -T; it sets the same page top margin as --margin-top.
Recommended Free Tools
Is a numeric value for --header-spacing measured in pixels?
No. The command-line documentation defines header spacing in millimetres; a value such as 3 means 3 mm.
Where should I look when a deployed server behaves differently from my workstation?
Compare wkhtmltopdf --version, --extended-help, page geometry, installed fonts, and access to header resources. Different binaries and Qt builds can expose different behavior.
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.
