# wkhtmltopdf — Convert HTML to PDF Using WebKit

> A command-line tool that renders HTML pages into PDF documents and images using the Qt WebKit engine. wkhtmltopdf faithfully reproduces CSS-styled pages including headers, footers, table of contents, and page breaks.

## Install

Save in your project root:

# wkhtmltopdf — Convert HTML to PDF Using WebKit

## Quick Use
```bash
# Install
apt-get install wkhtmltopdf   # Debian/Ubuntu
brew install wkhtmltopdf       # macOS

# Convert a webpage to PDF
wkhtmltopdf https://example.com output.pdf

# Convert a local HTML file with options
wkhtmltopdf --page-size A4 --margin-top 20mm report.html report.pdf
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-215b7909
Author: AI Open Source