Recommended Free Tools
Set wkhtmltopdf’s page margins with the global options --margin-top (short form -T) and --margin-bottom (short form -B). Values must include a unit, such as 20mm or 2cm:
wkhtmltopdf --margin-top 20mm --margin-bottom 25mm input.html output.pdfPlace these options before the input document and output filename. If you use the C/C++ library, set the corresponding global PDF settings, margin.top and margin.bottom. The correct numbers depend on your printable area and any header or footer; wkhtmltopdf does not define one universal recommendation.
CLI syntax for top and bottom margins
A normal command-line conversion accepts the margin options before the input and output objects:
wkhtmltopdf --margin-top 20mm --margin-bottom 25mm input.html output.pdfThe short aliases are useful in scripts:
wkhtmltopdf -T 20mm -B 25mm input.html output.pdf--margin-top controls the blank area between the top edge of the PDF page and the document body. --margin-bottom controls the equivalent area at the bottom. The official usage documentation lists these as page options in the wkhtmltopdf usage reference.
#1 Best Overall
Use a unit-bearing value
Do not pass a bare number when you need predictable output. Use a physical unit such as mm, cm, in or pt. For example:
wkhtmltopdf --margin-top 0.75in --margin-bottom 36pt input.html output.pdfThe library settings reference illustrates the same idea with a value such as 2cm. Keep both margins explicit in automated jobs so a change in a wrapper’s defaults cannot alter your layout.
Choosing values that fit your page
A margin reduces the rectangle available to your HTML. If the PDF page is 210 mm wide by 297 mm high and you specify 20 mm at the top and 25 mm at the bottom, the nominal vertical content area is 252 mm before accounting for headers, footers, and any layout behavior in the HTML. Large margins can therefore create extra pages or cause content to move.
Start from the content you must preserve
- Measure or estimate the space needed for the body, tables, images and signature areas.
- Reserve additional room when a header or footer is enabled.
- Render a sample PDF and inspect the first and last pages rather than relying only on arithmetic.
- Change one setting at a time so you can identify whether a defect comes from the margin or from the HTML.
Headers and footers need their own space
wkhtmltopdf provides header and footer switches plus separate spacing controls. A header that appears clipped, overlaps the body, or is outside the page usually needs a larger top margin, a smaller header-spacing value, or both. The libwkhtmltox settings reference specifically warns that excessive header spacing can place a header outside the PDF and says that increasing margin.top can correct it. Apply the same reasoning to a footer and the bottom margin.
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 →Repair Windows errors before they cause bigger problemsFix Now →wkhtmltopdf
--margin-top 30mm
--margin-bottom 25mm
--header-html header.html
--footer-html footer.html
--header-spacing 5
--footer-spacing 5
input.html output.pdfThe exact header and footer options available to your executable can vary by build, so confirm them with its built-in help and then inspect the rendered PDF.
Setting margins through libwkhtmltox
Applications embedding wkhtmltopdf use global PDF settings instead of CLI flags. Set:
margin.top = "2cm"
margin.bottom = "2cm"These are global settings, not per-element CSS margins. They define the page frame used by the PDF converter. The official libwkhtmltox settings reference documents margin.top and margin.bottom, including unit-bearing examples.
Keep the interface distinction clear
| Integration | Top setting | Bottom setting | Where it is applied |
|---|---|---|---|
| CLI | --margin-top or -T |
--margin-bottom or -B |
Before input and output arguments |
| libwkhtmltox global PDF settings | margin.top |
margin.bottom |
Global PDF configuration passed to the converter |
Wrappers in other languages often expose these same settings under their own property names. Check the wrapper’s documentation to ensure it is writing global PDF options rather than web-page CSS.
Free tools Windows power users keep installed
One-click scans. No signup required.
Margins versus CSS and page size
CLI margins are page-level whitespace. CSS such as body { margin: 20mm; } adds spacing inside the HTML viewport as well. Using both can double the apparent margin. Decide which layer owns the spacing: use wkhtmltopdf margins for a consistent PDF frame, and use CSS for spacing that belongs to a particular component.
Also check the paper-size and orientation options. Changing from portrait to landscape changes the available content rectangle even when the top and bottom margin values stay the same. A wide table may still overflow horizontally; increasing or decreasing vertical margins will not fix that problem.
Repeatable workflow for a reliable PDF
- Check the executable. Run
wkhtmltopdf --version(orwkhtmltopdf -V) and record the result with your build or deployment artifact. - Make a minimal test. Convert a small HTML file containing a heading, a paragraph, a long table and a footer-sized block.
- Set explicit units. Start with values such as
20mmand25mm, then adjust for your design. - Add headers or footers. Increase the relevant page margin before increasing spacing if the header or footer collides with body content.
- Inspect every boundary. Look at the first page, a page containing a table break, and the final page for clipping, overlap and unexpected blank space.
- Automate regression checks. Keep a known input and compare page count and visual output after changing the binary, wrapper, paper size or templates.
Troubleshooting margin problems
The option appears to do nothing
- Confirm the option is before the input and output arguments in a standard command.
- Check spelling: the long forms are
--margin-topand--margin-bottom; the short forms are uppercase-Tand-B. - Use a unit-bearing value and check the command’s help output for the installed build.
- Make sure a wrapper is not applying its own defaults after your setting.
The header is clipped or missing
Increase --margin-top (or margin.top) and review header spacing. A large spacing value can place the header outside the page; reducing that spacing may be necessary. Render again and inspect the PDF rather than assuming the header’s HTML height.
The footer overlaps content
Increase the bottom margin, reduce footer spacing, or shorten the footer. Long unbroken content and tables can also push body material into the reserved area, so test a page containing the worst-case row or paragraph.
The PDF has unexpected extra pages
Reducing the usable vertical area can create an additional page. Check top and bottom margins, header/footer reservations, CSS body margins, explicit page breaks and oversized elements. Reduce only the setting that is creating unnecessary whitespace; do not remove margins needed for printing.
Results differ between machines
Record wkhtmltopdf --version, the operating system, the wrapper version and all command-line options. The available references do not establish a complete compatibility matrix across versions, builds, wrappers and platforms, so validate the exact binary used in production.
Printing and production considerations
Leave a physical safety area
Desktop PDF viewers can display edge-to-edge content, but a physical printer may have a non-printable area. If the document will be printed, keep important text and rules inside a conservative margin and test on the target printer. Do not infer printer tolerances from wkhtmltopdf’s page settings.
Prefer deterministic configuration
Put margin values in the same configuration source as paper size, orientation, header/footer templates and other PDF options. Log the final command or settings object for failed jobs. This makes a layout change attributable and allows a previous configuration to be restored.
Use the official references
The project’s documentation landing page describes the generated documentation set. For option names, consult the usage documentation; for embedded applications, consult the library settings reference.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual goal is a clean image or PDF of a web page rather than a locally controlled wkhtmltopdf conversion, ScreenshotNeo makes the capture a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response reports the page verdict and billing status in X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.
Use the API documentation at screenshotneo.com/docs/ for the full option set. This basic call returns a WebP image:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent Python:
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)Equivalent 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}`);ScreenshotNeo includes full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets plus arbitrary viewports, retina scale, PDF paper size/margins/orientation/page ranges, HTML/CSS-to-image, custom CSS and JavaScript, pre-capture clicks, hidden selectors, waits for selectors/delays/network idle, request and resource blocking, custom headers/cookies/user agents/Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed public-image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which eases migration.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsThe Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; higher plans are Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000) and Business ($249 for 1,000,000). Yearly billing provides two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to start.
FAQ
Can I use inches instead of millimetres?
Yes. Pass a unit-bearing value such as 0.75in; the setting syntax accepts numeric values with units.
Are these options CSS margins?
No. They are wkhtmltopdf page settings. CSS margins are applied inside the rendered HTML and can add additional spacing.
Where do I set margins in an embedded application?
Use the global PDF settings margin.top and margin.bottom in libwkhtmltox or the corresponding properties exposed by your wrapper.
Frequently Asked Questions
Can I use inches instead of millimetres?
Yes. Pass a unit-bearing value such as 0.75in; the setting syntax accepts numeric values with units.
Are these options CSS margins?
No. They are wkhtmltopdf page settings. CSS margins are applied inside the rendered HTML and can add additional spacing.
Where do I set margins in an embedded application?
Use the global PDF settings margin.top and margin.bottom in libwkhtmltox or the corresponding properties exposed by your wrapper.
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.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →
