The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
For a fixed custom height, use --page-height with an explicit unit:
wkhtmltopdf --page-height 100mm input.html output.pdfSet the corresponding width with --page-width. This creates one page geometry for the output; it does not, according to the documented controls, automatically measure each page’s content and assign a different height. If you need receipt-style pages that grow with content, test the exact wkhtmltopdf binary and wrapper you deploy.
What “variable page height” means in wkhtmltopdf
The phrase can describe two different requirements:
- Custom fixed size: every output page uses a height you choose, such as 100 mm.
- Content-dependent size: each page becomes exactly as tall as its rendered HTML, or each receipt gets its own height.
wkhtmltopdf documents controls for the first requirement. The command-line option --page-height <unitreal> sets the page height, while --page-width <unitreal> sets the width. The references do not document automatic per-page content-height detection. Treat that behavior as unconfirmed until you test your installed build, HTML, and calling library.
#1 Best Overall
Set a fixed custom height from the command line
Minimal command
wkhtmltopdf --page-height 100mm input.html output.pdfReplace 100mm with the dimension required by your document. Include the unit rather than relying on a default; explicit units make scripts easier to audit and avoid differences between distributions or builds.
Set width and height together
wkhtmltopdf --page-width 80mm --page-height 200mm input.html receipt.pdfThis is useful for narrow receipts, labels, and other custom paper formats. Width and height describe the page box; margins, headers, footers, CSS, and pagination still affect where content appears inside it.
Use a named paper size when a standard is sufficient
wkhtmltopdf --page-size A4 input.html output.pdfThe documented default paper size is A4. Use --page-size for a named format such as A4 or Letter, and use the explicit width and height options when the required dimensions do not match a named size. Do not combine a named size and custom dimensions casually: decide which geometry your application is meant to control and verify the resulting PDF.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Units and dimension syntax
Dimension settings are unit-bearing values such as 100mm, 12in, or 4cm. The Debian Bookworm manual describes the page-height default unit as millimeters, but an explicit suffix is clearer and safer for portable automation. Confirm the accepted syntax of the actual executable in your deployment, especially when upgrading packages or switching operating systems.
| Use case | Example | What it controls |
|---|---|---|
| Custom height | --page-height 100mm |
Fixed output page height |
| Custom width | --page-width 80mm |
Fixed output page width |
| Named paper | --page-size A4 |
Standard paper geometry |
| Library height | size.height = "4cm" |
Fixed height through the library API |
| Library width | size.width = "12in" |
Fixed width through the library API |
Configure height through the library API
The library settings expose equivalent size fields. Set size.height and, when needed, size.width to strings containing units:
{
"size": {
"width": "80mm",
"height": "200mm"
}
}The exact object shape and method names depend on the language binding. Map these values to the binding’s documented settings rather than assuming that a command-line flag can be passed unchanged. If the wrapper also exposes size.pageSize, choose either a named paper size or explicit dimensions according to the wrapper’s precedence rules, then inspect the generated PDF.
Fixed height versus content-sized output
When fixed height is the right model
- You print on a known label or receipt stock.
- A downstream system requires a consistent PDF media box.
- You can tolerate normal pagination when content exceeds the chosen height.
- You want reproducible dimensions across jobs.
When you actually need content-dependent height
- Each receipt should be one page with no unused lower area.
- A single invoice should end immediately after its final row.
- Different records in one batch require different page heights.
--page-height alone does not establish that behavior. A fixed height can still produce additional pages when content does not fit, and shrinking the layout is not the same as changing the page geometry. For a content-sized workflow, render representative short, medium, and long documents with the exact binary and wrapper you will ship. Inspect page count, page breaks, and the PDF media-box dimensions using your normal PDF tooling. Record the result as a property of that setup, not as a universal wkhtmltopdf guarantee.
Smart shrinking is not automatic page-height calculation
Smart shrinking is a layout fitting or scaling feature. The command-line description frames it as changing the pixel-to-DPI ratio; the library reference describes intelligent shrinking in terms of fitting more content on a page. Neither description makes it a content-measurement system that assigns a new height to every page.
If text is unexpectedly small, compare runs with shrinking enabled and disabled using the same width, height, margins, fonts, and HTML. Keep the setting that meets your layout requirement, but evaluate scale and page dimensions separately. Disabling shrinking may expose overflow; enabling it may fit more content while reducing its physical size.
A practical implementation workflow
- Define the physical geometry. Write down the target width, height, margins, orientation, and whether the output is one page or a paginated document.
- Choose one sizing route. Use
--page-sizefor a standard format or explicit--page-widthand--page-heightfor custom stock. - Make units explicit. Use values such as
80mm,100mm, or4cmin scripts and library settings. - Render realistic HTML. Include the longest labels, images, tables, and fonts your production data can generate.
- Check pagination. Confirm whether overflow creates another page, clips content, or interacts with margins and CSS page-break rules.
- Measure the PDF. Verify media-box dimensions and page count with the PDF inspection tools used by your pipeline.
- Freeze the environment. Record the wkhtmltopdf version, package source, wrapper version, fonts, and command-line options so later upgrades can be compared.
Common problems and fixes
The PDF is still A4
Check that the command reaching wkhtmltopdf contains --page-height and that no wrapper later overwrites it with --page-size A4. Inspect the generated PDF rather than relying on application logs.
The unit is rejected or interpreted unexpectedly
Use an explicit suffix such as mm, cm, or in. Compare the installed binary’s help output and the package documentation for that build. Do not assume every wrapper accepts the same spelling or object type.
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 problemsContent spills onto another page
A height setting does not guarantee one-page output. Reduce content, adjust margins, control CSS page breaks, or choose a larger fixed height. Smart shrinking may alter scale, but it does not turn the document into an automatically measured page.
Content is clipped
Check CSS overflow rules, fixed-height containers, margins, and elements positioned outside the page box. Test with shrinking disabled and enabled to determine whether scaling is masking a layout problem.
Different machines produce different breaks
Fonts, wkhtmltopdf builds, wrapper defaults, device settings, and HTML timing can change layout. Pin the executable and fonts, wait for required assets, and compare the actual PDF dimensions and page breaks in a controlled environment.
A library setting has no effect
Confirm that the binding maps size.height and size.width to the document settings rather than to a different object. Log the final options passed to the renderer and check for later overrides.
Performance, reliability, and cost considerations
Custom dimensions do not by themselves make rendering faster or slower. Runtime is more often affected by HTML complexity, remote assets, JavaScript, fonts, and the number of pages. For reliable batch jobs, keep input assets reachable, avoid layout that depends on unbounded network timing, and test the largest expected document. If you require a single content-sized page, include that requirement in automated PDF assertions; a successful process exit is not proof that the visual result is correct.
There is no universal documented workflow in the reviewed references for automatically calculating a different height for every page. Any wrapper-specific workaround should be treated as an implementation detail and regression-tested after upgrades.
Or skip the browser setup
If your actual goal is a clean image or PDF capture of a web page rather than local wkhtmltopdf rendering, ScreenshotNeo provides a one-request API. It accepts a URL and can return PNG, JPEG, WebP, or PDF. Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the page verdict and billing status in headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo documentation for options such as page dimensions, full-page capture, PDF paper settings, CSS or JavaScript, waits, selectors, headers, cookies, geolocation, caching, asynchronous jobs, and bulk capture.
Recommended Free Tools
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is included on every plan. Create a free ScreenshotNeo account to get started.
FAQ
Can I use decimals?
Use the unit-bearing syntax accepted by your binary or binding, then verify the resulting PDF dimensions. The documented examples establish unit-bearing values, not a universal rule for every wrapper’s decimal parser.
Does page height change when orientation is landscape?
Orientation changes how width and height are interpreted by the renderer. Set and verify both dimensions explicitly when orientation matters.
The Bottom Line
Use --page-height (and usually --page-width) for a fixed custom page. Do not assume it creates automatically content-sized pages; validate that requirement with the exact wkhtmltopdf build and wrapper in your application.
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.
