wkhtmltopdf converts one or more HTML pages, URLs, or local files into a PDF. The basic shape is wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output-file>: put document-wide settings first, list page/cover/TOC objects in the order you want them rendered, and finish with the output filename.
This guide explains the argument scopes, practical layout and rendering switches, headers and footers, tables of contents, batch operation, diagnostics, version differences, and the security controls needed for server-side conversion.
1. Verify the executable and discover its manual
Check the binary that will actually run in your environment before relying on defaults:
wkhtmltopdf --version
wkhtmltopdf --help
wkhtmltopdf --extended-help
wkhtmltopdf -HThe project’s downloads page identifies the stable series as 0.12.6, released June 11, 2020. Package maintainers sometimes build it with different Qt patches or omit patched-Qt features, so the version string alone is not a complete compatibility guarantee. Record the output of --version in deployment documentation and test the installed build rather than assuming every package behaves like another 0.12.6 build.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
2. The command structure: global options, objects, output
A command has three logical parts:
- Global options affect the document run, such as paper size, orientation, margins, logging, and metadata.
- Objects describe content. A page object is a URL or file; a
coverobject adds a cover page; atocobject generates a contents page. - Output file is the final argument, normally ending in
.pdf.
Objects are emitted in the order supplied. A cover has no headers or footers and is excluded from the table of contents. A TOC is an object, not merely a switch, so place it where it should appear.
wkhtmltopdf https://example.com example.pdf
wkhtmltopdf cover cover.html toc chapter-1.html chapter-2.html book.pdfGlobal options belong before the objects. Options that apply to an individual page, including many header, footer, and loading settings, may be placed globally or attached to the relevant page object according to the manual.
3. A practical first command
Start with the smallest useful invocation:
wkhtmltopdf https://example.com example.pdfFor a landscape letter document with a larger top margin:
wkhtmltopdf --page-size Letter --orientation Landscape --margin-top 20mm https://example.com example.pdfThe input can be an HTTPS URL, an HTTP URL, or a local HTML file path. Quote paths containing spaces and use an explicit output path in automated jobs.
4. Page geometry and PDF layout
Paper size and orientation
--page-size A4selects A4, the documented default.LetterandLegalare also named paper sizes.--orientation Portraitis the documented default; useLandscapefor wide tables or screenshots.--page-widthand--page-heightaccept custom dimensions when a named paper size is unsuitable.
Margins and shrinking
Set each margin independently with --margin-top, --margin-bottom, --margin-left, and --margin-right. The manual documents 10 mm as the default left and right margin. Values include units such as mm, cm, in, or pt.
Smart shrinking is enabled by default in the documented manual. It lets the WebKit renderer reduce content to fit the page width. --disable-smart-shrinking makes layout more literal, which can preserve intended sizes but also create horizontal overflow or clipped content. If a table is unexpectedly tiny, inspect the page’s CSS width and test this switch together with a suitable paper size.
Rank #2
Images and JPEG quality
--image-dpi defaults to 600 in the manual and --image-quality defaults to 94 for JPEG compression. These settings influence output size and image fidelity; they do not repair a source image that is already low resolution. Use --no-images only when deliberately producing a text-only PDF.
5. JavaScript, loading, and media behavior
Dynamic pages
JavaScript is enabled by default. Disable it with --disable-javascript when scripts are unnecessary or undesirable. For pages that render asynchronously, add a delay:
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 problemswkhtmltopdf --javascript-delay 1500 https://example.com/dashboard dashboard.pdfThe documented default delay is 200 milliseconds. A fixed delay is a timing compromise: too short can capture an incomplete page, while too long increases job time. When the application exposes a reliable status value, --window-status READY can wait for that window status instead of guessing a delay.
CSS media and resource failures
--print-media-typeselects print CSS; screen media is the default.--load-error-handling abort|ignore|skipcontrols page-load failures and defaults toabort. Choose deliberately:abortprotects correctness, whileignoreorskipcan produce a PDF when a noncritical resource fails.- Media load failures have a separate setting and default to
ignore.
For reproducible output, make the page’s fonts, stylesheets, images, and scripts reachable from the conversion host and decide whether a missing asset should fail the job or be tolerated.
6. Local files, cookies, headers, and authentication
Local-file access is restricted by default. --enable-local-file-access enables local access, while --disable-local-file-access prevents reading other local files unless explicitly allowed. Prefer a narrow allow-list:
wkhtmltopdf --allow /srv/reports/assets /srv/reports/index.html report.pdfRepeat --allow for each directory genuinely required. Do not enable broad filesystem access simply to make a missing image appear.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchThe manual also provides options for cookies, custom HTTP headers, proxy settings, HTTP authentication, POST fields, and user stylesheets. Use them to reproduce the request context your page needs, but avoid placing secrets directly in shell history or process listings. In CI, inject credentials through the runner’s secret mechanism and restrict log output.
7. Headers, footers, outlines, and table of contents
Text headers and footers
Use --header-left, --header-center, --header-right, and the corresponding --footer-* options. For example:
wkhtmltopdf --header-right "Page [page] of [topage]" --footer-center "Internal" input.html output.pdfSupported replacement tokens include [page], [frompage], [topage], [webpage], [section], [subsection], [date], [isodate], [time], [title], and [doctitle]. Use --header-html or --footer-html when a styled HTML fragment is more appropriate. Font, line, and spacing controls are available in the manual.
Outlines and titles
--outline is enabled by default in the documented manual; --no-outline disables PDF bookmarks. --outline-depth 2, for example, limits the bookmark tree to two heading levels. Bookmarks are derived from heading structure in patched-Qt builds. Set metadata explicitly with --title "Quarterly report"; otherwise the first document title is used when available.
TOC object
Add toc as an object to create a contents page from heading tags. TOC options control its caption, indentation, dotted leaders, links, and stylesheet:
wkhtmltopdf cover cover.html toc --toc-header-text "Contents" chapter-1.html chapter-2.html book.pdfKeep the object order intentional: cover first, TOC next, then chapters is a common arrangement.
Rank #4
- Funny saying for any front-end developer, web developer, computer programmer, computer systems engineer, mobile app developer, software developer, or code lover who likes to code, make funny programming jokes, and take memorable photos.
- Wear it proudly at International Programmers' Day, school, coding classes, or coding communities! It also makes a funny present for a computer programming lover friend.
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
8. Batch conversion with standard input
--read-args-from-stdin lets each input line act as a separate invocation, combined with arguments passed on the command line. It is useful when many jobs would otherwise pay repeated process-start overhead, but the manual supplies no quantified performance improvement.
printf '%sn' "https://example.com one.pdf" "https://example.org two.pdf" | wkhtmltopdf --read-args-from-stdinValidate and quote generated lines carefully. A URL or filename containing spaces must be escaped according to the argument format expected by your shell and build.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →9. Diagnostics and failure recovery
Blank or partially rendered PDF
- Check whether the page is JavaScript-driven; increase
--javascript-delayor use--window-status. - Confirm that required assets are reachable from the conversion host and that print CSS is not hiding content.
- Run with
--log-level info(the documented default) orwarn/errorto focus output. Use--log-level noneonly when another system captures errors.
Missing images, fonts, or local styles
Inspect URL schemes, permissions, certificate trust, and local-file policy. Add a narrowly scoped --allow path or enable local access only when the input is trusted and the directory is controlled.
Job aborts on one broken resource
Leave --load-error-handling abort when completeness matters. If a known optional resource should not fail the document, test ignore or skip and monitor the resulting PDF for silent omissions.
Layout is clipped or unexpectedly scaled
Compare paper size, orientation, margins, CSS width, and smart shrinking. Wide content often needs landscape orientation, a larger custom page width, or a responsive stylesheet rather than ever-smaller text.
Options behave differently on another machine
Compare wkhtmltopdf --version, package source, and Qt patch status. Distribution builds can omit patches, changing available features and rendering behavior.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
- Programming Language Lover Code Apparel. App or Web Design and Development Expert Funny Dress. Best Valentines Idea For Coding Lover. HTML Code or Meaning Costume
- Funny I Know HTML - How To Meet Ladies Computer Programmer Quotes
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
10. Security requirements for server-side use
The project explicitly warns: “Do not use wkhtmltopdf with any untrusted HTML – be sure to sanitize any user-supplied HTML/JS, otherwise it can lead to complete takeover of the server it is running on!” Treat submitted HTML, JavaScript, URLs, cookies, and headers as hostile inputs.
- Sanitize HTML and remove scripts or dangerous URL schemes unless they are required.
- Run conversion as a dedicated low-privilege user with a temporary working directory.
- Restrict outbound network access and filesystem permissions to what the job needs.
- Use operating-system confinement such as AppArmor where appropriate. The project’s AppArmor guidance says local-file restrictions are useful but not a sole defense, and its example profile must be customized.
- Never pass untrusted strings to a shell command without safe argument handling; use a process API with an argument array.
- Redact cookies, authorization headers, and source HTML from logs.
11. Or skip the browser setup
If your goal is a clean screenshot or PDF of a public URL rather than a locally controlled WebKit conversion, ScreenshotNeo provides a single-call website screenshot API and MCP server. It accepts consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the result with X-Page-Verdict and X-Billed headers.
See the ScreenshotNeo API documentation for all options, including PDF paper size, margins, landscape mode, page ranges, custom JavaScript and CSS, selectors, waits, cookies, headers, geolocation, blocking rules, caching, signed links, asynchronous webhooks, bulk capture, and usage reporting. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThere is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is included on every plan. Create a free ScreenshotNeo account.
Recommended Free Tools
12. A production checklist
- Confirm the executable version and Qt packaging.
- Place global options before ordered page, cover, and TOC objects.
- Set paper geometry and margins deliberately.
- Choose JavaScript delay or window-status behavior for dynamic pages.
- Decide how failed resources should affect the job.
- Keep local-file access disabled or allow only specific directories.
- Test headers, footers, outlines, and TOC headings with representative content.
- Sanitize input and apply OS-level confinement for untrusted or multi-tenant workflows.
- Capture logs and retain the exact command configuration needed to reproduce a failure.
Frequently Asked Questions
What does -H do?
It prints the extended command-line manual, including options that may not appear in the short help output.
Can one command combine several HTML files?
Yes. Supply multiple page objects; wkhtmltopdf writes them in the order listed before the output filename.
Why does a package labeled 0.12.6 differ from another installation?
Builds can use different Qt patches or omit patched-Qt features, so rendering and available behavior may vary by distributor.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
