wkhtmltopdf.org

What is wkhtmltopdf?

wkhtmltopdf is an open-source command-line tool that converts HTML documents into PDF files. It uses the Qt WebKit rendering engine and runs entirely headless, meaning it needs no display or graphical environment. A companion tool, wkhtmltoimage, does the same job for image formats, and a C library is available for developers who want to embed the rendering engine in their own software.

What that means in practice

If you already produce HTML—from a web page, a template, or a generated report—you can turn it into a PDF by running a single command. The project's own example renders a live URL to a file:

wkhtmltopdf http://google.com google.pdf

Because it runs headless, it fits naturally into servers, cron jobs, and build pipelines where no desktop session exists. The project lists invoices, birthday cards, and other printable artifacts among typical uses, and it supports command-line options such as adding a table of contents.

Who it suits

• Developers and sysadmins who want scriptable, repeatable PDF output without a browser window.
• Backend services that generate invoices, tickets, or reports from HTML templates.
• Anyone on a headless server who cannot run a full desktop browser.

Trade-offs to weigh

The Qt WebKit engine is older than the engines in current browsers, so very modern CSS and JavaScript may render differently from what you see in Chrome or Firefox. If your HTML depends on cutting-edge layout or scripting, test the output before committing. For simple, well-structured HTML—the kind most invoices and reports use—it is a lightweight and dependable choice.

Next step

Download a precompiled binary or build from source, then run the tool against a sample HTML file. If you need precise control over margins, headers, or a table of contents, consult the auto-generated manual referenced on the project site. The project is maintained by Ashish Kulkarni and was originally created by Jakob Truelsen; source, downloads, and documentation are hosted at wkhtmltopdf.

How do I install wkhtmltopdf on my system?

Install wkhtmltopdf by downloading a precompiled binary for your operating system from the project's official downloads, or by building it from source if no suitable binary exists. The tool is a command-line program, so after installation you run it from a terminal rather than opening a graphical app. It renders HTML to PDF (and images) using the Qt WebKit engine and runs entirely headless, meaning no display service is required—useful on servers and in automated pipelines.

Typical installation paths

Verify and first run

After installing, confirm it works by checking the version from a terminal, then convert a simple page:

wkhtmltopdf http://google.com google.pdf

If that produces a PDF, the installation is sound. If the command is not found, the binary is not on your PATH—move it to a standard location or add its folder to PATH. On headless Linux servers, missing shared libraries (often Qt-related) are the most common failure; installing the distribution's dependencies usually resolves it.

Decision criteria

Choose the precompiled binary when you want the fastest setup and your OS is supported. Choose your package manager when you want updates handled for you, accepting that the packaged version may lag behind upstream. Build from source only when you need a specific rendering behavior or platform support that the binaries do not provide, since it takes the most time and tooling.

For options such as adding a table of contents or controlling page size, see the auto-generated manual linked from wkhtmltopdf.

How can I use wkhtmltopdf to generate PDFs from HTML pages with custom headers and footers?

Use wkhtmltopdf as a command-line step in a script: point it at an HTML file or URL, then add --header-* and --footer-* options to draw content in the page margins.

Basic pattern

wkhtmltopdf \
  --header-center "Monthly Invoice" \
  --footer-right "Page [page] of [topage]" \
  --footer-font-size 8 \
  invoice.html invoice.pdf

The tool renders HTML into PDF (and image formats) using the Qt WebKit engine and runs headless, so it fits cron jobs, CI pipelines and server-side batch generation. The same engine also powers the image variants, which is useful when you need a PNG preview alongside the PDF.

Headers and footers

Two approaches work:

• Inline text options — --header-left, --header-center, --header-right, --footer-left, --footer-center, --footer-right, plus font, size and spacing options. Fast for simple titles.
• HTML documents — --header-html header.html and --footer-html footer.html. Better when the header needs a logo, table layout or styling.

Substitution variables make page-aware footers practical: [page], [topage], [title], [date], [time], [frompage], [webpage]. A common choice is a right-aligned Page [page] of [topage] footer with a smaller font size.

Margins matter. Header and footer content is drawn in the margin area, so set --margin-top and --margin-bottom large enough to hold it; otherwise text can overlap body content. --header-spacing and --footer-spacing control the gap between the header/footer and the page body.

A concrete scenario

A small SaaS team generates monthly invoices from an HTML template. The header HTML carries the company logo and invoice number; the footer HTML carries bank details on the left and Page [page] of [topage] on the right. A shell loop reads a customer list, substitutes values into the template, and calls the tool once per customer. Because it is a command-line tool with a C library available, the same logic can move into a long-running service without changing the rendering approach.

Trade-offs to weigh

The main practical risk is rendering fidelity: pages that look correct in a current browser may render differently here. Build a small set of representative HTML samples and compare output before committing to it for customer-facing documents.

Next step

Run one real document through the tool with only --footer-right "Page [page] of [topage]" first, confirm the footer sits inside the margin without overlap, then add the HTML header. Consult the auto-generated manual for the full option list, and see wkhtmltopdf for downloads and documentation.

What are the alternatives to wkhtmltopdf for HTML to PDF conversion?

For most new projects, the practical alternatives to wkhtmltopdf fall into three groups: modern headless browsers (Chromium via Puppeteer or Playwright), dedicated rendering services, and library-based PDF generators such as WeasyPrint or Prince. wkhtmltopdf itself is a command-line tool that renders HTML to PDF and images with the Qt WebKit engine, runs headless, and also exposes a C library; its WebKit base is the main reason people look elsewhere, since it lags on newer CSS and JavaScript behavior.

Headless Chromium (Puppeteer, Playwright)

The closest like-for-like replacement. You point a real browser at a page or an HTML string and call its PDF function. Best when your HTML relies on modern CSS (flexbox, grid), web fonts, or JavaScript that must execute before printing. Trade-off: heavier install, slower cold starts, and more memory per conversion than a small CLI. Page setup (margins, headers, footers) is configured through the API rather than command-line flags.

CSS paged-media engines (WeasyPrint, Prince)

These render HTML and CSS directly, with strong support for print concepts like page breaks, running headers, and generated tables of contents. WeasyPrint is open source; Prince is commercial. They suit invoices, reports, and books where layout fidelity to print matters more than executing arbitrary JavaScript. Trade-off: they implement a print-focused CSS subset, so browser-specific JavaScript rendering is out of scope.

Rendering services and APIs

Hosted conversion APIs (for example DocRaptor or PDFShift) take an HTML document or URL and return a PDF. Useful when you want to avoid maintaining a browser stack, need to scale conversion horizontally, or must render untrusted HTML in isolation. Trade-off: per-document cost, network dependency, and sending content to a third party.

Quick comparison

How to choose

Start from what your HTML actually needs. If it is mostly static markup with print styling, a CSS paged-media engine gives cleaner page control. If it depends on client-side JavaScript or current CSS, use headless Chromium. If you would rather not operate a browser at all, a hosted API removes that burden.

A concrete test: take one representative document (an invoice with a logo, a table, and a page footer) and render it with two candidates. Compare page breaks, font rendering, and header/footer placement, then time a batch of 100 conversions. That single exercise usually settles the choice faster than feature lists. For browser automation specifically, see Playwright and Puppeteer.

How do I troubleshoot common errors in wkhtmltopdf?

Troubleshooting wkhtmltopdf usually comes down to understanding that it is a headless Qt WebKit renderer driven from the command line, not a browser. Most "errors" are mismatches between what a modern browser does and what this older engine can render, or between the environment the tool runs in and the environment you tested in.

Start with the error text, then classify it

Run the command with output visible rather than swallowing it in a script. The message itself usually sorts the problem into one of three buckets:

• Render/layout problems — blank pages, missing images, wrong fonts, broken JavaScript. These are WebKit capability and resource-loading issues.
• Process problems — the tool exits non-zero, hangs, or crashes. These are environment, library, or input issues.
• Output problems — the PDF is produced but has odd page breaks, headers, or margins. These are option and CSS issues.

Common cases and what to change

• Blank or partially blank PDFs. Often the page relies on JavaScript that finishes after the snapshot, or on resources loaded over a network the headless process cannot reach. Add a delay with --javascript-delay, and check that relative asset paths resolve from the correct base. If the HTML is local, use --enable-local-file-access so linked files are permitted.
• Missing or substituted fonts. The renderer can only use fonts installed in the environment where it runs. Install the fonts on the server or container, or embed them via @font-face with an absolute path.
• Headers, footers and page numbers not appearing. These are supplied through --header-html and --footer-html with separate HTML files, and they need their own margins reserved via the --margin-top and --margin-bottom options. A common mistake is styling the header in the main document's CSS, where it has no effect.
• Page breaks in the wrong place. Use CSS page-break-before and page-break-inside: avoid on the elements you want kept together, and test against the actual page size you pass with --page-size.
• Hangs or crashes on a server. This is frequently a headless-environment issue: missing shared libraries, no writable temp directory, or a sandboxed container blocking the process. Confirm the binary runs at all by converting a trivial local HTML file first.

A practical debugging sequence

1. Reduce to a minimal HTML file with one line of text. If that fails, the problem is the installation or environment, not your document.
2. Add your CSS, then your images, then your JavaScript, testing after each step.
3. If it works interactively but fails in cron or CI, compare the working directory, environment variables, and font set between the two contexts.

When to use something else

wkhtmltopdf is convenient for invoices, reports, and one-off page captures, and the wkhtmltopdf documentation covers the full option list and the C library. Its trade-off is the older rendering engine: if your HTML depends on modern CSS or a current JavaScript framework, you will spend more time fighting the renderer than the document. In that case, a headless Chrome-based converter that matches your browser's engine will reproduce your layout with far less tuning, at the cost of a heavier runtime.

A reasonable decision rule: if the document is mostly static HTML and CSS you control, wkhtmltopdf is quick to script; if it is a modern web app page or must match Chrome exactly, choose a Chromium-based tool instead.

What are the licensing terms and commercial use options for wkhtmltopdf?

wkhtmltopdf is released under the LGPLv3, an open source license. That means you can use it commercially, including inside a business, without paying a license fee to the project. The practical condition is in the "L" (Lesser) part: if you distribute software that links to wkhtmltopdf's C library, you generally must allow users to replace or relink that library — typically by dynamically linking to it rather than statically embedding it, and by providing the license and source access for the library itself. If you only run the command line tool as a separate program (for example, calling wkhtmltopdf from a script or server process to turn HTML into a PDF), that linking requirement usually does not apply to your own code.

There is no separate commercial edition, paid tier, or royalty described for the tool itself. "Commercial use options" in practice mean one of these:

• Use it as-is under LGPLv3 — free, including in paid products, as long as you meet the relinking and notice conditions when you distribute it as part of your software.
• Keep it at arm's length — run the command line binary as a standalone process. This is the simplest route for most web apps and internal invoice or report generation.
• Link the C library dynamically — if you want the library API, dynamic linking is the usual way to stay comfortable with LGPLv3.
• Replace it if your constraints are stricter — teams that cannot accept LGPLv3 obligations sometimes switch to a permissively licensed renderer or a commercial PDF service.

A concrete scenario: a small SaaS generates monthly invoices for customers. It installs the wkhtmltopdf binary on its own servers and calls it per invoice. No distribution of the binary to customers occurs, so the LGPLv3 obligations are minimal. The same company shipping a desktop app that embeds the C library statically would need to review its linking and notice practices before release.

Next step: decide whether you are distributing the tool or using it internally, and whether you link the C library or call the binary. That distinction, not a fee, determines your obligations. The project's own download and documentation pages at wkhtmltopdf are the place to confirm the current license text and library documentation before you build it into a product.