ScreenshotNeo

BlogHow-to

How to Set Variable Page Height in wkhtmltopdf

Set a fixed custom PDF page height with wkhtmltopdf’s --page-height option, and learn what to do when you need content-sized pages instead.

By the ScreenshotNeo team30 September 20267 min read

How to Set Variable Page Height in wkhtmltopdf

To set a custom page height in wkhtmltopdf, pass --page-height with a number and unit. For example, this command requests a 100 mm page height:

wkhtmltopdf --page-height 100mm input.html output.pdf

Use --page-width to set the width too. The important distinction is that these options set page dimensions; the documented controls do not describe automatically measuring rendered content and assigning a different height to each page. If you need a single content-sized receipt or a page per input record, validate the behavior with your installed wkhtmltopdf build and wrapper.

This guide covers the CLI and library settings, standard paper sizes, units, pagination and shrinking, plus practical diagnostics. For a website screenshot or PDF workflow that does not require setting up a local browser capture, ScreenshotNeo offers a one-request screenshot API and PDF capture.

1. Set a fixed custom page height from the command line

Use the global page options before the input and output arguments. Include an explicit unit so the requested size is clear:

wkhtmltopdf --page-height 100mm --page-width 80mm input.html receipt.pdf

This asks wkhtmltopdf to render input.html using pages 80 mm wide and 100 mm high, then write the result to receipt.pdf. Replace those dimensions with the size required by your document. The example does not make the height dynamic: every page uses the selected page dimensions, subject to the renderer’s pagination and layout behavior.

For a remote page, the input can be a URL:

wkhtmltopdf --page-height 100mm --page-width 80mm https://example.com/receipt receipt.pdf

Confirm the exact option syntax supported by the binary you deploy. wkhtmltopdf distributions and wrappers can differ, and the relevant documentation does not establish the behavior of every customized build.

Check the options available in your installed binary

wkhtmltopdf --version
wkhtmltopdf --extended-help

Look for --page-height, --page-width, and --page-size in the help output. If an option is missing or rejected, check which executable your application invokes and whether it is the expected build.

2. Choose custom dimensions or a named paper size

The documented default paper size is A4. Use --page-size when a standard named size is the goal; use explicit width and height when the output needs custom dimensions.

Need CLI option Example
Standard paper --page-size --page-size Letter
Custom height --page-height --page-height 100mm
Custom width --page-width --page-width 80mm
Custom width and height Both dimension options --page-width 80mm --page-height 100mm

Do not combine a named size and custom dimensions without checking how the installed binary resolves them. If exact physical dimensions matter, specify the custom width and height explicitly and inspect the resulting PDF page size.

3. Use explicit units

The Debian Bookworm manual describes the page-height default unit as millimeters. Explicit units are easier to read and reduce ambiguity, especially when commands move between environments. The C library settings also accept unit-bearing values such as 12in and 4cm.

Unit Example Use
Millimeters 100mm Common for paper and receipts
Centimeters 10cm Convenient for larger metric dimensions
Inches 4in Common when dimensions come from an inch-based specification

Choose one unit convention for your configuration and make it explicit. The exact accepted syntax can vary by release or build, so use the local help and library reference that correspond to the binary or package you ship.

4. Configure page dimensions through the library

If an application uses the wkhtmltopdf C library, the settings reference exposes size.pageSize, size.width, and size.height. The following is a settings-shaped example, not a standalone program: apply these values through the binding’s settings API, then add the input and output objects using that binding’s documented calls.

// Settings values for a wkhtmltopdf library binding
settings["size.pageSize"] = "Custom";
settings["size.width"] = "80mm";
settings["size.height"] = "100mm";

Bindings do not all expose settings through the same language-level API. Check the wrapper’s own documentation for how it represents global settings, how it handles strings, and whether it accepts custom dimensions. Use the library’s documented unit-bearing dimensions rather than assuming a bare number has the same meaning across interfaces.

When a wrapper has a different configuration shape

  1. Find the wrapper’s equivalent for global page settings.
  2. Set both width and height if the target is a custom page shape.
  3. Pass unit-bearing strings, such as 80mm and 100mm.
  4. Render a short and a long representative document and inspect page dimensions and breaks.

The C library settings are documented; a particular wrapper’s field names and defaults are not established by those settings alone. Do not assume a wrapper option exists unless its documentation confirms it.

5. Fixed page height versus content-sized output

“Variable page height” can mean two different things:

A fixed page-height setting defines the page boundary; it does not by itself measure the content.
A fixed page-height setting defines the page boundary; it does not by itself measure the content.
  • Custom fixed height: choose one page height for the document with --page-height.
  • Content-sized height: measure the rendered content and make a page fit it, potentially with different heights for different records.

The reviewed wkhtmltopdf references document page dimensions and named paper sizes. They do not document automatic per-page content-height detection. This means the fixed-height option is not evidence that a document will grow to fit its content. Behavior can depend on the build, HTML, wrapper, and desired pagination semantics.

If you need a content-sized receipt, first decide whether the output is one long page or a set of pages. Then validate the exact application path with representative short and long content:

  1. Render a minimal input and a realistic long input using the same binary and options as production.
  2. Inspect the PDF’s actual page dimensions and where content breaks.
  3. Check whether content overflows, is clipped, or continues on another page.
  4. If the height must be derived from content, determine whether your application can measure the rendered output and set dimensions before PDF generation.

Do not rely on a result from a different wkhtmltopdf build or wrapper as a universal guarantee. The source references do not define a universal content-sized page workflow.

6. Understand smart shrinking separately

Smart shrinking concerns fitting or scaling content. The CLI describes it as changing the pixel-to-DPI ratio; the library reference describes intelligent shrinking in terms of fitting more content on one page. Neither description makes it a page-height control.

When page dimensions look correct but content scale or fit is wrong, investigate shrinking and layout separately from --page-height. Compare the output with shrinking enabled and disabled in the exact binary you use. Keep the page width, height, input, and other rendering settings constant so you can see which behavior changed.

7. Troubleshoot common problems

Symptom Likely cause What to check
The command rejects --page-height The invoked executable may not support the option, or a wrapper may parse arguments differently. Run wkhtmltopdf --version and --extended-help; confirm the binary path and wrapper syntax.
The page uses an unexpected size A named paper size, wrapper default, or unit interpretation may be affecting the result. Set explicit width and height with units; inspect the generated PDF page dimensions.
The content still spans multiple pages A fixed page size does not itself measure content or disable pagination. Check content length, page dimensions, margins, and actual page breaks. Validate the intended one-page or multi-page behavior.
Content is clipped or does not fit The page is too short or narrow for the rendered content, or layout scaling differs from expectations. Increase the custom dimensions as needed and evaluate smart shrinking separately.
Different machines produce different output They may use different wkhtmltopdf builds, wrapper settings, or input rendering conditions. Compare versions, exact arguments, library settings, and input. Test the production binary.
A library wrapper ignores the dimensions The wrapper may use a different settings API or may not pass the values to the global settings object. Consult that wrapper’s documentation and verify the effective settings before conversion.

8. Reliability, performance, and cost considerations

For reproducible output, record the wkhtmltopdf version, custom page dimensions, unit convention, wrapper version, and relevant shrinking setting alongside the generation configuration. Keep a representative input in your own validation process so upgrades or environment changes can be checked against the page size and pagination you expect.

ScreenshotNeo removes common consent banners, newsletter popups, and chat widgets before capture.
ScreenshotNeo removes common consent banners, newsletter popups, and chat widgets before capture.

Page dimensions alone do not establish how quickly a conversion will run or whether a particular document will fit. The references here provide option semantics, not performance benchmarks. Test realistic short and long inputs under your own workload, especially when layout, page count, or external resources vary.

Cost depends on how you run and host the conversion; the wkhtmltopdf option documentation does not specify infrastructure costs. Estimate from your own deployment and volume rather than treating a page-size flag as a cost guarantee.

Or skip the browser setup

If your real task is to capture a website as an image or PDF, ScreenshotNeo accepts a URL through its API. See the API documentation for the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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)
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 removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

FAQ

Does --page-height set every page to a different height?

The documented option sets an output page height. The reviewed references do not describe automatically measuring content and changing height for each page.

What is the default page size?

The project usage text documents A4 as the default. You can request another named size with --page-size.

Will smart shrinking make a page taller?

Smart shrinking is described as a fitting or scaling behavior. Treat it separately from the page-height setting.

Can I use this for a receipt?

You can specify custom dimensions, such as a narrow width and a chosen height. If the required height depends on receipt content, validate how your exact build and wrapper paginate that content.

Primary references