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.
See what current Chrome prints, with nothing to install: make the long invoice in the try-it box.
Which wkhtmltopdf you have matters
There are two different builds, and they disagreed on most rows of our test. Run wkhtmltopdf --version:
wkhtmltopdf 0.12.6.1 (with patched qt)is the official download.wkhtmltopdf 0.12.6, with nothing after it, is Debian's package fromapt install wkhtmltopdf.
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
- Your templates use JavaScript (charts, totals filled in by a script): Chrome.
- No scripts, and you work in Python: WeasyPrint. Our WeasyPrint image was 314 MB, against 855 MB for Chrome with fonts.
- Laravel with Snappy: see Laravel PDFs without Chrome or Node for what each Laravel option needs on the server.
- You'd rather not run either: use an API.