Replacing wkhtmltopdf

Tested: wkhtmltopdf 0.12.6.1 (official build, patched Qt) and 0.12.6 (Debian 12 package), Puppeteer 25.16.0 with Chrome 156, WeasyPrint 66.0, 2026-11-04

wkhtmltopdf's GitHub repository was archived on January 2, 2023, and its packaging repository on August 28, 2023, so 0.12.6.1 is the last build. It renders with Qt WebKit. The project's own status page says the WebKit it bundles hasn't been updated since 2012. Nothing will fix its CSS support or its security from here.

The usual replacements are Chrome, driven by Puppeteer or Playwright, and WeasyPrint. We printed the same test document with each, to show what changes when you switch.

Which wkhtmltopdf you have matters

There are two different builds, and they disagreed on most rows of our test. Run wkhtmltopdf --version:

Debian's package uses the system's newer QtWebKit instead of the project's patched Qt. That gets it some modern CSS, but it drops features. It ignored our page number footer and printed this warning:

The switch --footer-center, is not support using unpatched qt, and will be ignored.

Side by side

One document: three boxes in a flex row, three in a grid, a CSS variable colour, a coloured background, a @media print rule, an ES5 script, a modern script, and a 40-row table with tall rows and page-break-inside: avoid. A4, 15mm and 12mm margins.

wkhtmltopdf 0.12.6.1 (official) wkhtmltopdf 0.12.6 (Debian) Chrome 156 (Puppeteer) WeasyPrint 66
Flexbox Stacked vertically Side by side Side by side Side by side
CSS grid Stacked vertically Stacked vertically Laid out Laid out
CSS variable colour Ignored (black) Worked Worked Worked
ES5 script Ran Ran Ran No scripts at all
Modern script (arrow function, template literal) Didn't run Ran Ran No scripts at all
Table header on every page Yes Page 1 only Yes Yes
Rows with page-break-inside: avoid Kept whole 2 of 40 split Kept whole Kept whole
"Page 1 of 4" footer --footer-center Ignored footerTemplate CSS @page
Background colours Printed Printed Only with printBackground: true Printed
@media print rules Only with --print-media-type Applied Applied Applied
16px text in the PDF About 20% smaller About 23% smaller As written As written

What changes when you move to Chrome

1. Text gets bigger. wkhtmltopdf's "smart shrinking" scales pages down. The same 16px text was about 20% smaller from the official build than from Chrome. With --disable-smart-shrinking, the official build matched Chrome exactly. To keep the old size without editing your CSS, use Puppeteer's scale: 0.8, which matched wkhtmltopdf's default text size exactly in our test.

2. Background colours disappear. wkhtmltopdf prints them by default. Puppeteer doesn't. Our green box printed with no background, which left its white text nearly invisible. Add printBackground: true.

3. Print CSS starts applying. The official wkhtmltopdf uses your screen styles unless you pass --print-media-type, and page.pdf() uses print styles. If you have old @media print rules that never ran before, they will now. To print screen styles as wkhtmltopdf did, call await page.emulateMediaType('screen') before page.pdf().

4. Headers and footers become templates. --header-html and --footer-html pages become headerTemplate and footerTemplate strings, and [page] and [topage] become <span class="pageNumber"></span> and <span class="totalPages"></span>. Templates have their own gotchas. Our page numbers guide covers them, plus a plain CSS alternative for Chrome 131 and later.

5. Modern CSS and JavaScript work. Flexbox, grid, CSS variables and modern JavaScript all worked in Chrome.

Flag by flag

wkhtmltopdf Puppeteer
-s A4 format: 'A4'
-O Landscape landscape: true
-T 15mm -B 15mm -L 12mm -R 12mm margin: { top: '15mm', bottom: '15mm', left: '12mm', right: '12mm' }
--footer-center "Page [page] of [topage]" displayHeaderFooter: true, a footerTemplate, and headerTemplate: '<div></div>' to keep Chrome's default header out
--print-media-type Nothing: it's the default. page.emulateMediaType('screen') gives the old default.
--no-background Nothing: it's the default. printBackground: true keeps backgrounds.
Smart shrinking (the default) scale: 0.8 matched its text size
--disable-smart-shrinking Nothing: Chrome doesn't shrink.
--javascript-delay 1000 Have your script set a marker when it's done, then await page.waitForSelector('body[data-ready]')

A fixed delay is a guess. In our test, a script that filled in a total after 0.8 seconds was missing from a PDF printed straight away and present after waitForSelector.

The same job in Puppeteer

This replaces wkhtmltopdf -s A4 -T 15mm -B 15mm -L 12mm -R 12mm --footer-center "Page [page] of [topage]" invoice.html invoice.pdf:

import puppeteer from 'puppeteer';
import { pathToFileURL } from 'node:url';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto(pathToFileURL('invoice.html').href, { waitUntil: 'load' });
await page.pdf({
  path: 'invoice.pdf',
  format: 'A4',
  margin: { top: '15mm', bottom: '15mm', left: '12mm', right: '12mm' },
  printBackground: true, // wkhtmltopdf printed backgrounds
  displayHeaderFooter: true,
  headerTemplate: '<div></div>',
  footerTemplate: `<div style="width: 100%; font-size: 9px; text-align: center;">
    Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>`,
});
await browser.close();

Chrome needs fonts on the server just as wkhtmltopdf did. If you're moving to Docker, see Puppeteer PDF fonts in Docker.

Or WeasyPrint, if you don't need scripts

WeasyPrint is a Python library and command-line tool with its own layout engine, so there's no browser to run. It laid out our flex and grid boxes, repeated the table header, kept rows whole and printed backgrounds without extra options. It doesn't run JavaScript at all.

Page numbers go in your CSS:

@page {
  size: A4;
  margin: 15mm 12mm;
  @bottom-center { content: "Page " counter(page) " of " counter(pages); font-size: 9px; }
}
pip install weasyprint
weasyprint -s footer.css invoice.html invoice.pdf

On Debian we also needed the Pango libraries: apt-get install libpango-1.0-0 libpangoft2-1.0-0.

Which to choose

Moving off wkhtmltopdf and don't want to run Chrome? PagedPDF is an HTML-to-PDF API on current Chrome. Send HTML, get a PDF back. Table headers repeat, rows stay whole, and page numbers take one footer option.

More guides