How to set page size and margins in wkhtmltopdf

Use --page-size to choose a named paper format, or set both --page-width and --page-height for custom dimensions. Set printable whitespace independently with --margin-top, --margin-bottom, --margin-left, and --margin-right. Include units such as mm, cm, or in.

For example, this command requests portrait Letter paper with 15 mm top and bottom margins and 12 mm side margins:

wkhtmltopdf \
  --page-size Letter \
  --orientation Portrait \
  --margin-top 15mm \
  --margin-bottom 15mm \
  --margin-left 12mm \
  --margin-right 12mm \
  input.html output.pdf

See the wkhtmltopdf usage manual for CLI options and the libwkhtmltox settings reference for the library equivalent.

1. Choose a named page size or custom dimensions

The documented default is A4. Use --page-size for a named format such as A4, A3, Letter, or Legal. The manual points to Qt’s paper-size enumeration for the complete list; accepted formats can depend on the installed build, so verify uncommon values against your binary.

wkhtmltopdf --page-size A4 input.html output.pdf
wkhtmltopdf --page-size Letter input.html output.pdf
wkhtmltopdf --page-size Legal input.html output.pdf

When a named format does not fit, specify both dimensions. For example, 210 mm by 297 mm describes an A4-sized canvas:

wkhtmltopdf \
  --page-width 210mm \
  --page-height 297mm \
  input.html output.pdf

The manual describes width and height as finer-grained controls. Use explicit units; the library reference also gives examples in centimetres and inches.

2. Set orientation and all four margins

Orientation is controlled separately with --orientation Portrait or --orientation Landscape. Portrait is the documented default. Margins are independent: set each edge to the whitespace your document needs.

Purpose	CLI option	Example
Top whitespace	`--margin-top`	`15mm`
Bottom whitespace	`--margin-bottom`	`15mm`
Left whitespace	`--margin-left`	`12mm`
Right whitespace	`--margin-right`	`12mm`

The usage manual documents 10 mm as the default for left and right margins. Do not assume that same documented default applies to top and bottom; set all four explicitly when predictable geometry matters.

3. Put options in the right place

For a single input file or URL, put page geometry options before the input and output arguments. This makes their global scope clear:

wkhtmltopdf --page-size A4 --margin-top 15mm input.html output.pdf

wkhtmltopdf can also combine page objects, covers, and a table of contents, which are placed in output order. Options may be global or per object, and options classified as global must go in the global options area. In a multi-object command, check the manual’s option classification rather than assuming a setting applies to every object.

4. Use the equivalent libwkhtmltox settings

When configuring the library instead of the CLI, set the PDF global settings for size and margins. The setting reference names them size.pageSize, size.width, size.height, orientation, and margin.top, margin.bottom, margin.left, and margin.right. Values are UTF-8 strings.

// Illustrative settings names and values for the PDF global settings object.
// Adapt these assignments to the language binding you use.
settings["size.pageSize"] = "Letter";
settings["orientation"] = "Portrait";
settings["margin.top"] = "15mm";
settings["margin.bottom"] = "15mm";
settings["margin.left"] = "12mm";
settings["margin.right"] = "12mm";

For custom geometry, use size.width and size.height, for example "210mm" and "297mm", instead of relying on a named size. The exact object construction and API calls depend on the binding; the settings reference documents the names and value format.

5. Check the resulting geometry

Choose a named paper format or decide the exact width and height.
Select portrait or landscape orientation.
Set all four margins with explicit units.
For multiple page objects, confirm whether each option is global or object-specific.
Generate the PDF and inspect its page dimensions and content placement in your normal document review workflow.

The available research documents the options and defaults but does not verify a particular installed binary or conversion. Check wkhtmltopdf --version and that build’s help output when a format or behavior matters in deployment.

6. Troubleshoot common problems

Symptom	Likely cause	What to check
Output remains A4	The size option was omitted, placed outside the applicable scope, or the command was assembled differently than intended.	Put `--page-size` or both custom dimension flags in the global options area before the input; inspect the command and installed help.
Custom dimensions are ignored or rejected	One dimension is missing, a value lacks a unit, or that build does not accept the supplied form.	Provide both `--page-width` and `--page-height` with units such as `210mm`; confirm accepted syntax in the local help.
Content sits too close to an edge	The corresponding margin is unset or smaller than needed.	Set the specific edge flag, such as `--margin-left 12mm`; set all four margins explicitly for repeatable layout.
Landscape output has unexpected geometry	Orientation and dimensions may be getting mixed or applied at different scopes.	Choose either a named size with `--orientation Landscape` or explicit width and height, then check scope in multi-object commands.
Only some objects use the settings	Options can be global or per object.	Review the manual’s classification and place global settings in the global options section.

7. Practical reliability and cost notes

Page geometry is a rendering configuration, not a guarantee that every deployed wkhtmltopdf build accepts every named size. The cited CLI manual identifies itself as version 0.12.6 with patched Qt; check the actual version and help output in your environment when reproducibility matters. Keep explicit units and margins in the command or settings you deploy, and review multi-object option scope. No benchmark or conversion test is claimed here.

The documented flags do not add a per-request service charge; operational cost depends on how and where you run wkhtmltopdf. If you instead need a hosted website-to-PDF or screenshot request, ScreenshotNeo offers PDF capture and documents its API options at the ScreenshotNeo docs.

Or skip the browser setup

For a hosted PDF capture, make one GET request. This example saves the response body as a PDF; consult the API documentation for PDF parameters and output settings.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -d format=pdf \
  -o page.pdf

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com", "format": "pdf"},
    timeout=90,
)
r.raise_for_status()
open("page.pdf", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
  format: 'pdf'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo request failed: ${res.status}`);
await require('node:fs/promises').writeFile('page.pdf', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server lets AI agents use screenshot and PDF capture tools. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. See ScreenshotNeo and its API docs, then sign up for 1,000 free screenshots a month with no card.

FAQ

Can I set only one custom dimension?

The documented custom-size controls are page width and page height. Supply both when defining a custom page geometry.

Are margins measured in pixels?

The references show unit-bearing values such as centimetres and inches. Use explicit physical units such as mm, cm, or in.

Where can I find the complete set of named paper sizes?

The usage manual points to Qt’s paper-size enumeration and notes examples including A3, Letter, and Legal. Check the installed build for the formats it accepts.