Use wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>: put document-wide settings before the input page, add page, cover, or table-of-contents objects in the order you want them to appear, then give the output PDF filename. A basic conversion is wkhtmltopdf https://example.com example.pdf. The installed build matters: check wkhtmltopdf --version and wkhtmltopdf -H before relying on an option or default.
Understand the command’s three parts
The command-line manual documents this general form:
wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>
Global options set defaults or behavior for the conversion. Objects specify what content to include and in what order. The final argument names the PDF file to write. For a simple web page, the input URL is a page object:
wkhtmltopdf https://example.com example.pdf
A local HTML filename can be used in place of the URL. The project homepage uses the same input-then-output pattern. Options and defaults described below come from the project’s manual for version 0.12.6 with patched Qt; other builds can differ. See the command-line manual and the downloads page.
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 →#1 Best Overall
Global options
These appear before the objects and usually affect the whole output, such as paper dimensions, orientation, margins, and diagnostics.
Objects
A page object is an input URL or file. A cover object adds a cover page without headers or footers and excludes it from the table of contents. A toc object inserts a contents page based on document headings. Objects appear in the PDF in the order given.
Output file
Place the output filename after all objects and their applicable options. A PDF extension such as .pdf makes the intended format clear.
Set page size, orientation, and margins
For example, this command selects US Letter paper in landscape orientation and sets a 20 mm top margin:
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 errorswkhtmltopdf --page-size Letter --orientation Landscape --margin-top 20mm https://example.com example.pdf
The manual documents A4 as the default paper size, portrait as the default orientation, and 10 mm as the default for left and right margins. Set all margins explicitly when a layout must be predictable across environments.
| Purpose | Arguments | Documented behavior |
|---|---|---|
| Paper size | --page-size A4, Letter, or Legal |
A4 is the documented default. |
| Orientation | --orientation Portrait or Landscape |
Portrait is the documented default. |
| Custom dimensions | --page-width and --page-height |
Use these instead of a named paper size when you need custom dimensions. |
| Margins | --margin-top, --margin-bottom, --margin-left, --margin-right |
The manual gives 10 mm as the left and right default; specify the values you need for the other sides. |
Choose landscape when the content is too wide for portrait, or use custom width and height when the target page is not a standard paper size. Margins control printable space; reducing them can fit more content but leaves less room around the page edges.
Rank #2
- LIGHTWEIGHT AND FOLDABLE STRUCTURE: Foldable design (30x6x8cm) and lightweight (1000g) make it portable for travel or home use. Compact shape fits perfectly on your workbench without taking up much space
- SIMPLE CONNECTION: Works with USB connection without the need for additional programs for quick installation. Simple controls make it easy to operate both beginners and regular users with regular size papers
- QUICK DOCUMENT PROCESSING: Automatically scan suggestions one page per second, greatly increase productivity. Ideal for workplaces, schools, legal/financial areas where large capacity is required
- TEXT CONVERSION TECHNOLOGY: Smart OCR function works in over 200 languages, changes scanned files to editable text for easy storage and editing Seamless digital conversion of paper documents improves workflow
- EXCELLENT IMAGEING: Equipped with a 16MP clear camera, this portable document scanner produces crisp, accurate images of documents and keeps important content intact. Perfect for striking scans of contracts, receipts and books
Control what the page renders and when
Web pages may depend on JavaScript, images, remote stylesheets, or browser timing. These options govern how wkhtmltopdf handles those dependencies. The documented defaults are tied to the manual’s 0.12.6 patched-Qt build.
JavaScript and delayed content
- JavaScript is enabled by default. Use
--disable-javascriptto turn it off if the page does not need it or you want to avoid script-driven changes. --javascript-delay <msec>waits a specified number of milliseconds; the documented default is 200 ms. Increase it when a page needs extra time to populate, but expect longer conversions.--window-status <string>waits for a page status string. This is useful when the page exposes a known status after rendering; it is not a substitute for checking that the expected content actually loaded.
Images and print styling
- Images load by default.
--no-imagesdisables image loading and printing. --print-media-typeselects print CSS. Without it, screen media is the documented default.--enable-smart-shrinkingis enabled by default in the manual;--disable-smart-shrinkingturns off WebKit’s intelligent shrinking strategy.
If a PDF’s spacing differs from the browser view, check whether the site has separate print styles before changing page geometry. If images are absent, check that image loading has not been disabled and that the resources can be reached.
Resource loading errors
--load-error-handling accepts abort, ignore, or skip; the documented default is abort. These choices affect how the conversion proceeds when a page resource fails. Media load failures have a separate setting and are documented to default to ignore. Select error behavior deliberately: ignoring or skipping failed resources can produce a PDF that is incomplete without stopping the conversion.
Local files and allowed paths
The manual documents local-file access as disabled by default. --enable-local-file-access enables it, while --disable-local-file-access prevents reading other local files unless they are explicitly allowed. Use --allow <path> one or more times to grant access to specific paths needed by the HTML, such as local assets. Avoid broad access when a narrow path is enough.
Add headers, footers, outlines, and a table of contents
Text and HTML headers or footers
Set text in header and footer positions with options such as --header-left, --header-center, --header-right, --footer-left, --footer-center, and --footer-right. For example:
Recommended Free Tools
wkhtmltopdf --header-right "Page [page] of [topage]" https://example.com example.pdf
Documented replacement tokens include [page], [frompage], [topage], [webpage], [section], [subsection], [date], [isodate], [time], [title], and [doctitle]. For more complex header or footer layouts, provide HTML files with --header-html or --footer-html. Font, line, and spacing controls are also available. Header and footer options can be global or attached to a page object where applicable.
Table of contents and PDF bookmarks
A toc object creates a contents page using heading tags. Its options can adjust the caption, indentation, dotted lines, links, and stylesheet. For example, a page followed by a contents object and another page is written in that order in the command, and the objects appear in that order in the PDF. PDF outlines, or bookmarks, are enabled by default in the documented manual and are also derived from heading tags in the patched-Qt build. Use --no-outline to disable them or --outline-depth to limit their nesting depth; the documented default depth is 4.
These features depend on the source document having useful heading structure. If headings are missing or incorrectly nested, the contents page and outline will reflect that structure rather than infer a better one.
Set PDF metadata and inspect available options
--title <text>sets the PDF title. If omitted, the first document title is used when available.--image-dpicontrols image DPI; the documented default is 600.--image-qualitysets JPEG compression quality; the documented default is 94.--log-levelacceptsnone,error,warn, orinfo; the documented default isinfo.--versionreports the executable version;--helpand--extended-helplist command options.
For the manual that matches the executable in your environment, run wkhtmltopdf -H. Use wkhtmltopdf --version as well, especially on a server where the installed package may differ from a local development machine.
Combine multiple objects in a deliberate order
Objects are emitted in the sequence written. This lets you create a cover page, contents page, and one or more converted pages in a chosen order. Each object can have applicable page-specific options, while global options belong in the global-options area before the objects. A cover is intentionally different from an ordinary page: it has no headers or footers and is not included in the contents list.
When assembling a multi-object command, keep the output filename last and review the object order before running it. If an option appears to affect the wrong page, check whether it belongs globally or should be attached to a particular page object in the syntax supported by your installed build.
Use command-line options for authenticated or customized pages
The manual documents page options for cookies, custom HTTP headers, proxy settings, HTTP authentication, POST fields, and user stylesheets. They are useful when a page requires a session, must be rendered through a proxy, or needs a controlled style adjustment. Consult wkhtmltopdf -H for the exact option names and syntax available in your build; do not assume that every packaged version supports every feature identically.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →For repeated batch conversions, --read-args-from-stdin allows each input line to act as a separate invocation, with its arguments combined with those passed to the executable. The manual suggests this for batch jobs where startup time is a concern, but does not quantify a performance gain. Test it with the actual inputs and environment rather than assuming a speed improvement.
Check version and build compatibility
The project downloads page names 0.12.6 as its stable series and gives June 11, 2020 as its release date. That is version metadata, not a guarantee that a system package is identical: the page explains that some features depend on patched Qt and that distribution builds may omit those patches. As a result, an option or behavior described by the patched-Qt manual can differ in another package.
Before deploying a command, run wkhtmltopdf --version in the same environment that will execute it, then inspect wkhtmltopdf -H. Test a representative document, including its headers, local assets, and scripts, using that executable. The official references are the downloads page and the manual.
Troubleshoot common conversion problems
The PDF is missing dynamic content
Check whether JavaScript is enabled and whether the page needs more than the documented 200 ms delay. Try a larger --javascript-delay, or use --window-status if the page exposes a reliable completion status. A longer wait increases conversion time, and a status string only helps when the source page sets it as expected.
Local images or stylesheets are missing
If the HTML references local files, check the local-file access settings. Grant only the necessary locations with repeated --allow <path> options, or explicitly enable local-file access when appropriate. Also confirm that the referenced paths exist and are readable by the process running wkhtmltopdf.
The conversion aborts on a failed resource
The documented load-error default is abort. If a nonessential resource should not stop the whole job, consider ignore or skip, while verifying that the resulting PDF still contains the required content. Media load errors have separate handling.
Page layout is clipped or unexpectedly scaled
Confirm the paper size, orientation, and margins first. For wide pages, test landscape orientation or custom dimensions. Then check whether smart shrinking is enabled and whether the source page’s print CSS changes its layout under --print-media-type.
Headers, footers, or bookmarks do not appear as expected
Verify that the relevant options are supported by the installed build, and check the placement of global versus page-specific settings. For TOCs and outlines, inspect the source heading tags; these features derive their structure from headings rather than from arbitrary visual formatting.
Outdated 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 matchPC 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 & 11An option is rejected or behaves differently on a server
Compare wkhtmltopdf --version and wkhtmltopdf -H in the server environment with the version and help output used during development. A distribution package may not include patched Qt features available in the documented build.
Protect the server when converting HTML
The project’s downloads page 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 uploaded or user-generated HTML and JavaScript as dangerous input. Sanitization is important, but it should not be the only safeguard.
The project’s AppArmor page describes using AppArmor to limit filesystem access and command execution, and cautions that local-file restrictions should not be treated as the sole defense if a vulnerability is exploited. Its example profile must be customized for the application. Run conversion with access limited to the files it genuinely needs and use suitable operating-system confinement controls.
Or skip the browser setup
If the job is to capture a clean screenshot rather than assemble a PDF with wkhtmltopdf, ScreenshotNeo provides a website screenshot API and MCP server for developers. A GET request can return a PNG, JPEG, WebP, or PDF. For example, save a WebP capture with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the ScreenshotNeo API documentation for the request options and response details. Cookie banners are accepted or removed before capture, along with known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Where can I find the options supported by my installed wkhtmltopdf?
Run wkhtmltopdf -H in the environment where the conversion will run; package builds can differ.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does wkhtmltopdf use print CSS by default?
No. The documented default is screen media; --print-media-type selects print CSS.
Can wkhtmltopdf convert more than one page into a PDF?
Yes. It accepts multiple ordered objects, including pages, a cover, and a table of contents.
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.
