wkhtmltopdf Command Line Examples for Website to PDF Conversion

The basic command to convert a website to PDF is wkhtmltopdf https://example.com output.pdf. Put global options such as paper size and orientation before the page URL; put page-specific options after the page they affect. Confirm that your installed build supports the options you need: wkhtmltopdf is an older tool, and some features depend on a Qt-patched build.

Install and check your wkhtmltopdf build

Check whether the executable is available and inspect its version and supported options:

wkhtmltopdf --version
wkhtmltopdf --extended-help

The project describes wkhtmltopdf as an open-source command-line tool that renders HTML to PDF using Qt WebKit. Its upstream GitHub repository was archived on January 2, 2023 and is read-only. That does not establish compatibility with any particular modern website or system; test the pages and options your workflow depends on. Some features require a Qt-patched build, as noted in the project’s downloads guidance. See the project overview and repository status.

Basic command line examples

Convert a website

wkhtmltopdf https://example.com page.pdf

The first positional argument is the webpage URL; the final argument is the output PDF path. For another example, the upstream guide uses wkhtmltopdf http://google.com google.pdf.

Convert a local HTML file

wkhtmltopdf ./page.html page.pdf

Use a path that exists from the current working directory. If the HTML refers to local images, CSS, or fonts, those files must also be accessible to the renderer. Check local-file access restrictions and the installed build’s --allow option in extended help if assets do not appear.

Choose paper size and orientation

wkhtmltopdf --page-size A4 --orientation Landscape https://example.com page.pdf

Common documented controls include --page-size (for example, A4 or Letter) and --orientation (Portrait or Landscape). You can also set explicit dimensions with --page-width and --page-height, where supported by your build.

Set page margins

wkhtmltopdf --margin-top 15mm --margin-bottom 15mm https://example.com page.pdf

Margin values accept units such as millimeters. The usage reference also documents left and right margins. Leave room in the top and bottom margins if you add headers or footers.

Headers, footers, backgrounds, and print styles

Headers and footers can include page information, but exact switches and placeholders should be checked with wkhtmltopdf --extended-help because support can vary by build. A typical documented option pattern is:

wkhtmltopdf \
  --page-size A4 \
  --margin-top 20mm \
  --header-center "Quarterly report" \
  --footer-center "Page [page] of [toPage]" \
  https://example.com/report report.pdf

Some older or unpatched builds may reject header and footer switches; consult the installed help output before relying on them. Use adequate margins so page content does not overlap the header or footer.

Background printing and print media are separate concerns. The page options document --background and --no-background; background printing is enabled by default in the cited usage reference. The option for selecting print media is also documented, but verify its exact availability locally. If a site’s print stylesheet changes its layout, the PDF can differ from the screen version.

Wait for JavaScript-rendered pages

For pages that populate content after initial load, the usage reference documents a JavaScript delay and waiting for a chosen window.status value. For example:

wkhtmltopdf --javascript-delay 2000 https://example.com/dashboard dashboard.pdf

This waits for a fixed delay before capture; increase it only when the page needs more time. A status-based wait can be more targeted when the page itself sets a known status value. Check the installed build’s extended help for the exact switch syntax and behavior.

A delay cannot make unsupported browser APIs work, bypass authentication, or ensure that every asynchronous request has completed. Modern sites may rely on browser features that the older Qt WebKit engine does not implement.

Combine a cover, table of contents, and pages

wkhtmltopdf accepts multiple document objects: webpage pages, a cover, and a table of contents. Objects appear in the output in the order supplied. For example:

wkhtmltopdf \
  cover https://example.com/cover \
  toc \
  https://example.com/chapter-1 \
  https://example.com/chapter-2 \
  book.pdf

The cover does not appear in the table of contents and does not have headers or footers. A table of contents is generated from the document outline. If the output order or contents are unexpected, check the sequence of objects and whether the source pages expose headings suitable for the outline.

Option placement and useful controls

The command structure is wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>. Global options must be in the global options area before the objects. Page options can be global or placed after an individual page object, allowing per-page settings. Options from the global-options section cannot be placed in the object area. This placement rule is a frequent cause of rejected switches or settings applied to the wrong page.

Need	Documented option or pattern	Placement note
Paper format	--page-size A4	Global option, before objects
Orientation	--orientation Landscape	Global option, before objects
Margins	--margin-top 15mm	Global or page option as supported
Backgrounds	--background / --no-background	Page rendering option
JavaScript delay	--javascript-delay 2000	Check page-option support in installed help
Cookie values	--cookie NAME VALUE	Repeatable page option; encode values as required
Cookie jar	--cookie-jar path	Global option
PDF title	--title "Report"	Global option
Lower file size	--lowquality	Can reduce output quality
Less console output	--log-level error	Global option; verify accepted levels

The official usage reference lists many more controls, including proxy settings, allowed local paths, image quality and DPI, grayscale output, PDF outline settings, copies, and page-specific headers and footers. Use --extended-help as the authority for the binary actually installed on your machine.

Python and Node.js wrappers

These examples invoke the command line program as a child process. They assume wkhtmltopdf is installed and available on PATH, and they fail clearly if the command exits unsuccessfully.

Python

import subprocess

url = "https://example.com"
output = "page.pdf"

subprocess.run(
    ["wkhtmltopdf", "--page-size", "A4", url, output],
    check=True,
)
print(f"Wrote {output}")

Node.js

import { spawnSync } from "node:child_process";

const result = spawnSync(
  "wkhtmltopdf",
  ["--page-size", "A4", "https://example.com", "page.pdf"],
  { encoding: "utf8" }
);

if (result.error) throw result.error;
if (result.status !== 0) {
  throw new Error(result.stderr || `wkhtmltopdf exited with ${result.status}`);
}
console.log("Wrote page.pdf");

Pass arguments as an array rather than building a shell command string. This avoids shell quoting problems when URLs, paths, or titles contain spaces or special characters.

Troubleshooting

Symptom	Likely cause	What to do
wkhtmltopdf: command not found	Not installed, or executable is not on PATH	Install a build for your platform and confirm with wkhtmltopdf --version.
Unknown or unsupported option	Option unavailable in this build, or option is in the wrong position	Inspect --extended-help; move global options before objects and page options next to the relevant object.
Blank or incomplete page	Load failure, delayed JavaScript, unsupported browser feature, or blocked resource	Check the URL from the conversion environment, inspect logs, try a measured JavaScript delay, and verify whether the page depends on modern browser behavior.
Images or styles missing from local HTML	Relative paths resolve differently or local files are restricted	Use correct paths, make assets available, and consult --allow in the installed help.
Content clipped or too small	Paper size, orientation, margins, or long unbreakable content do not fit	Try landscape, adjust margins or explicit page dimensions, and check the rendered page layout.
Header/footer overlaps content	Insufficient top or bottom margin	Increase the corresponding margin and verify header/footer support in the current build.
Different output between machines	Different wkhtmltopdf builds, fonts, network access, or Qt support	Record --version, use a consistent environment, and check dependencies and available fonts.
PDF exists but conversion failed	Wrapper ignored a nonzero process exit or stale output remained	Check the process exit status and stderr; remove or replace stale output only after confirming the new conversion succeeded.

Performance, reliability, and cost

Conversion time depends on the page, its assets, network responses, JavaScript, and the local machine; the supplied sources give no universal benchmark. For a reliable batch workflow, set an application-level timeout, capture stderr and the exit code, write to a temporary output path, and publish the file only after a successful exit. Avoid increasing JavaScript delay globally when only some pages need it.

wkhtmltopdf is a local command-line tool, so there is no per-request ScreenshotNeo charge when using it locally; account for your own compute, maintenance, and deployment work. The upstream project is archived, and current website compatibility should be checked against the pages you need to render.

Or skip the browser setup

ScreenshotNeo is a website screenshot API that can also return a PDF. For a one-call PDF capture, follow the API documentation for the PDF request options and adapt the URL:

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

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Start with 1,000 free screenshots a month—no card required.

FAQ

Can wkhtmltopdf convert more than one URL into a single PDF?

Yes. Supply multiple page objects before the output filename. The order on the command line determines the order in the PDF.

Does a command that works on one machine guarantee the same output elsewhere?

No. Builds, Qt support, fonts, local file permissions, and network conditions can differ. Check the version and extended help in the environment that creates the PDF.

Is wkhtmltopdf actively maintained upstream?

The upstream GitHub repository is archived and read-only. Treat its behavior as build-dependent and verify compatibility with your pages.