wkhtmltopdf — Convert HTML to PDF Using WebKit

Introduction

wkhtmltopdf is an open-source command-line tool that uses a patched Qt WebKit rendering engine to convert HTML and CSS into high-fidelity PDF documents. It is widely used in server-side report generation, invoice rendering, and document automation pipelines.

What wkhtmltopdf Does

• Renders HTML pages to PDF with full CSS 2.1 and partial CSS 3 support
• Generates page headers and footers with dynamic page numbers and dates
• Creates a clickable table of contents from heading elements automatically
• Converts HTML to raster images (PNG, JPG, BMP, SVG) via the companion wkhtmltoimage tool
• Accepts input from URLs, local files, or standard input for pipeline integration

Architecture Overview

wkhtmltopdf embeds a patched build of Qt WebKit that adds printing-specific features like page breaks and header/footer injection. The tool loads the HTML, waits for JavaScript execution and resource loading to complete, then renders the result to a PDF via Qt's QPrinter backend.

Self-Hosting & Configuration

• Install from OS package managers or download static binaries from the project releases
• Run headless on servers without a display by using xvfb-run or the patched Qt build
• Pass options via the command line or an arguments file for repeatable builds
• Configure proxy, cookies, and custom HTTP headers for authenticated page rendering
• Embed in web applications using language bindings (Python: pdfkit, Ruby: wicked_pdf, Node: node-wkhtmltopdf)

Key Features

• Faithful CSS rendering via a real browser engine rather than ad-hoc parsers
• JavaScript execution support for dynamic content and charting libraries
• Custom headers and footers with HTML templates and variable substitution
• Page break control with CSS properties (page-break-before, page-break-after)
• Batch conversion of multiple URLs or files into a single combined PDF

Comparison with Similar Tools

• Puppeteer / Playwright — use headless Chromium for more modern CSS/JS support but require Node.js
• WeasyPrint — Python-based HTML-to-PDF with modern CSS but no JavaScript execution
• Prince — commercial engine with superior CSS Paged Media support
• Pandoc — converts Markdown/HTML to PDF via LaTeX; different rendering approach
• pdf-lib / jsPDF — programmatic PDF creation in JS; wkhtmltopdf takes HTML input

FAQ

Q: Is wkhtmltopdf still maintained? A: The project is in maintenance mode. It works well for existing use cases but new features are unlikely. For modern CSS/JS, consider Puppeteer or Playwright.

Q: Can it run on a headless server? A: Yes. The patched Qt build supports headless operation. On older systems, use xvfb-run as a fallback.

Q: How do I handle pages that require authentication? A: Pass cookies with --cookie or custom headers with --custom-header to authenticate requests.

Q: Does it support CSS Grid and Flexbox? A: Support is limited because the underlying Qt WebKit engine predates widespread Grid and Flexbox adoption. Use Puppeteer for modern layouts.

Sources

• https://github.com/wkhtmltopdf/wkhtmltopdf
• https://wkhtmltopdf.org/