Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
wkhtmltopdf 0.12.6 documents A4 as the default page size and names A3, Letter, and Legal as examples of alternatives. Those examples are not a complete list: the manual directs users to the Qt 4.8 QPrinter::PaperSize enum for the named sizes. If you need dimensions outside a named format, use --page-width and --page-height instead.
Which paper sizes can you use?
The wkhtmltopdf 0.12.6 usage manual says --page-size accepts a paper-size value from Qt 4.8’s QPrinter::PaperSize enum. It calls A3, Letter, and Legal examples, then links to the enum for the full set of named sizes. The linked enum is the appropriate reference for the names; the manual’s examples should not be treated as an exhaustive list. See the wkhtmltopdf usage documentation and the Qt 4.8 QPrinter PaperSize enum.
| Value | What the wkhtmltopdf manual establishes |
|---|---|
| A4 | Documented default page size. |
| A3 | Named example of a size selectable with --page-size. |
| Letter | Named example of a size selectable with --page-size. |
| Legal | Named example of a size selectable with --page-size. |
| Other named sizes | Refer to the Qt 4.8 enum linked by the manual. This article does not reproduce an exhaustive list. |
The documented examples include A-series formats and US-oriented Letter and Legal. They do not establish a geographic rule that changes the default: the documented default is A4.
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 →Use a named size from the command line
Pass the named format with --page-size. For example, this command requests Letter:
#1 Best Overall
wkhtmltopdf --page-size Letter input.html output.pdfReplace input.html with the HTML file or URL you want to render and output.pdf with the destination filename. To request A3 or Legal, substitute that documented name. If you omit --page-size, the 0.12.6 manual says the default is A4.
For another named format, use the spelling shown in the Qt enum rather than assuming a familiar shorthand or a name from another PDF tool will be accepted. The wkhtmltopdf manual delegates the full named-size list to that enum.
Set a custom width and height
When a standard named format does not meet your needs, specify dimensions with --page-width and --page-height. For example, the option pattern is:
wkhtmltopdf --page-width WIDTH --page-height HEIGHT input.html output.pdfReplace WIDTH and HEIGHT with dimension values and units accepted by the wkhtmltopdf binary you have installed. The usage documentation identifies width and height as the finer-control mechanism, but exact unit compatibility should be checked against that binary’s help output. Do not assume that custom is itself a valid value for --page-size; the documented route to custom dimensions is the separate width and height options.
For a library caller, the parallel settings are size.width and size.height; the page-size setting is size.pageSize. The libwkhtmltox settings reference documents these fields. Set the width and height when specifying dimensions directly, rather than treating a custom dimension as a named paper-size enum member.
Check the wkhtmltopdf binary you actually run
The cited usage manual identifies itself as wkhtmltopdf 0.12.6 with patched Qt and points to Qt 4.8. That documentation is a useful starting point, but it does not prove that every packaged or locally built binary has an identical Qt configuration. If a format or dimension matters to a production PDF, check the installed executable’s own usage or --extended-help output and render a representative document with that binary.
- Identify the executable used by your application. Check the path or package configuration so that you are not consulting help for a different installation.
- Inspect its option output. Run the binary’s help or extended-help command and confirm the available page-size, page-width, and page-height options.
- Render a small sample. Generate a test PDF with the exact name or dimensions your job will use.
- Inspect the resulting page. Confirm the PDF’s page dimensions and check that the rendered content fits the intended page.
This is especially important when moving a command from a development machine to a server or container: the cited manual describes a particular version/build context, not a guarantee about every deployment.
Diagnose common page-size problems
A requested name is rejected
Confirm that the argument is a name in the Qt 4.8 paper-size enum linked from the wkhtmltopdf manual, with the spelling expected by the option. A3, Letter, and Legal are explicit examples. If the name is not accepted by your installed binary, consult that binary’s help output; do not assume every distribution has the same Qt configuration.
The PDF is still A4
Check that --page-size is present in the command that actually runs, that its value is the intended one, and that the process is invoking the executable you inspected. A4 is the documented default, so a missing or ineffective size argument can leave the output at that default.
A nonstandard format does not work with --page-size
Use --page-width and --page-height for direct dimension control. The manual identifies these as the finer-control options; it does not document custom as a paper-size value.
The selected page size is right but the layout is not
Paper size and page layout are related but distinct concerns. First verify the generated PDF page dimensions. If those match your requested format, investigate the HTML and other print settings separately instead of changing the paper-size name at random. Render the same input with the same binary while changing one setting at a time so you can identify which change affects the result.
Free tools Windows power users keep installed
One-click scans. No signup required.
A command-line setting is not reflected in a library integration
Command-line switches and libwkhtmltox settings are different interfaces. In the library settings reference, use size.pageSize for a named size and size.width and size.height for direct dimensions. Verify the configuration passed to the library rather than assuming a command-line argument will be applied automatically.
Or skip the browser setup
If your actual goal is a clean screenshot of a web page rather than a PDF with a chosen paper size, ScreenshotNeo is a separate screenshot API and MCP server for developers. It does not replace wkhtmltopdf’s page-size controls or make a PDF layout decision. For a website screenshot, one GET request can return an image or PDF; the following cURL example saves a WebP screenshot of the wkhtmltopdf site. The API options are documented at ScreenshotNeo docs.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://wkhtmltopdf.org -o shot.webp- Cookie and consent banners are accepted before capture, and 60+ known consent platforms, newsletter popups, and chat widgets can be removed; each step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify the page verdict and billing status with headers.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for Claude, Cursor, and other MCP clients. - The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
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.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
