---
type: Article
title: "wkhtmltopdf vs headless Chromium: What changes when you switch | Marqius"
description: Try Marqius to keep your current PDF code. Use Chromium when your
  report needs a browser to load its data or draw its charts.
resource: https://marqius.com/blog/wkhtmltopdf-vs-headless-chromium/
tags:
  - marqius
  - journal
status: stable
sources:
  - id: official-page
    resource: https://marqius.com/blog/wkhtmltopdf-vs-headless-chromium/
    last_modified: 2026-11-20T07:33:03.895Z
generated:
  by: process:marqius-site-build
  at: 2026-11-20T10:17:10.036Z
x_marqius:
  language: en
  source_sha256: 8cab4a2f46f70d4f91f9dd24aeea5545c9cd138432984cded1b9228d5f2acc3b
  extraction: public-main-content
---

wkhtmltopdf migration

# wkhtmltopdf vs headless Chromium: What changes when you switch

Try Marqius to keep your current PDF code. Use Chromium when your report needs a browser to load its data or draw its charts.

Marqius November 20, 2026

Picture two documents. One is a plain invoice your app already sends through wkhtmltopdf. The other is a report whose charts only appear after the browser loads more data. Those two documents can point you toward different tools.

## Why this helps

**For the existing invoice, start with Marqius.** It’s a drop-in replacement for apps that start the wkhtmltopdf program. In a test copy of the app, point your library at Marqius, keep your invoice code and print the invoice again. [Find your library’s setting](https://marqius.com/blog/wkhtmltopdf-deprecated-alternatives/)

**For the report that needs a browser, try Chromium.** Headless Chromium is a browser that runs without an open window. Your app can tell it to load the report, wait for the chart and then print. That helps when a regular browser is already what makes the report work. You’ll need to change the PDF call and set up the print options.

## What changes in practice

| 
Existing wkhtmltopdf input

 | 

What to check with Chromium

 |
| --- | --- |
| 

`--page-size`, margins, orientation and zoom

 | 

Choose page format and margins in the PDF API or `@page`. Set `preferCSSPageSize` deliberately and compare the resulting page dimensions.

 |
| 

HTML headers and footers with page variables

 | 

Map them to `headerTemplate` and `footerTemplate`. Enable `displayHeaderFooter`, allocate margin space, and use Chromium's `pageNumber` and `totalPages` classes.

 |
| 

`--javascript-delay` or a completion signal

 | 

Wait for an app-defined ready element or condition. Wait for fonts too. A timer alone does not establish that the last table row arrived.

 |
| 

Screen CSS or `--print-media-type`

 | 

Puppeteer PDF generation uses print CSS by default. Compare the result with what the old invocation used and choose the media explicitly if required.

 |
| 

CSS, fonts and images beside a local file

 | 

Make each resource reachable from the browser's environment. For HTML supplied as a string, check how relative links are resolved.

 |
| 

A wkhtmltopdf table of contents or several input objects

 | 

Plan the document structure or assembly step explicitly. The browser PDF call prints one page context and does not parse wkhtmltopdf flags.

 |

[Puppeteer Page.pdf](https://pptr.dev/api/puppeteer.page.pdf) · [Puppeteer PDF options](https://pptr.dev/api/puppeteer.pdfoptions)

## Try both tools with the same invoice

These commands use a Debian 12 or 13 machine where you can run Docker and install Chromium. Run the browser from your regular user shell. Start with the sample invoice so both tools receive the exact same HTML.

### 1\. Set up Chromium and get the sample

Terminal

```
sudo apt-get update
sudo apt-get install -y chromium curl fonts-dejavu-core poppler-utils
mkdir -p marqius-chromium-demo
cd marqius-chromium-demo
```

The studio’s **Invoice 1001** uses three Marqius products as line items so you can see how they fit together. **Marqius wkhtmltopdf** keeps your existing PDF call working, **Studio** is where you design the document, and **Relay** generates it from a template and data. The sample amounts add up to **120.00 EUR** including VAT. Open `START-HERE.html` after unzipping to run the invoice and check a page break. [Download the print demo (ZIP)](https://marqius.com/download/wkhtmltopdf-demo/0.12.8/marqius-invoice-demo.zip) · [Open the invoice PDF](https://marqius.com/download/wkhtmltopdf-demo/0.12.8/expected-invoice.pdf)

If your team also checks files before they go to press, use the sample from Marqius Engine. It has a finished A4 size, 3 mm of bleed, real CMYK colour patches and a 100 mm reference you can measure at actual size. [Open the press test sheet](https://marqius.com/download/wkhtmltopdf-demo/0.12.8/marqius-press-proof.pdf)

Unzip the demo and put `invoice.html` in your test folder. If you're already in the terminal, you can get the same file with one command.

Terminal

```
curl -fsSLo invoice.html https://marqius.com/download/wkhtmltopdf-demo/0.12.8/invoice.html.txt
```

### 2\. Print it with Marqius

Terminal

```
docker run --rm --network none --mount "type=bind,source=$PWD,target=/data" \
  marqius/wkhtmltopdf:0.12.8 --page-size A4 invoice.html invoice-marqius.pdf
```

### 3\. Print the same HTML in Chromium

Terminal

```
chromium --headless --user-data-dir="$PWD/chromium-demo-profile" \
  --no-pdf-header-footer --print-to-pdf="$PWD/invoice-chromium.pdf" \
  "file://$PWD/invoice.html"
```

The profile is separate from your usual browser profile. If this is a report that loads more data after the page opens, drive Chromium from your app and wait for its ready signal before printing. The demo is a static invoice so you can compare the same input immediately. [Puppeteer PDF options](https://pptr.dev/api/puppeteer.pdfoptions)

### 4\. Check the results

Terminal

```
for pdf in invoice-marqius.pdf invoice-chromium.pdf; do
  printf '\n%s\n' "$pdf"
  pdfinfo "$pdf" | grep -E '^(Pages|Page size):'
  pdftotext "$pdf" - | grep -F '120.00 EUR'
done
```

Both should show one A4 page and **120.00 EUR**. Open them side by side to see where the table and total land. For the actual app, use a document that reaches a second page and one that needs JavaScript. The [public scoreboard](https://github.com/marqiushq/wkhtmltopdf-parity#the-scoreboard) covers the separate comparison of wkhtmltopdf and Marqius. [Use the harness with your own templates](https://github.com/marqiushq/wkhtmltopdf-parity#check-your-own-templates).

## Reader questions

### Can I point pdfkit or Snappy at headless Chromium?

Those wrappers expect the wkhtmltopdf command-line interface. Drive Chromium through a browser library or an HTTP service and map the PDF settings.

## Keep reading

[wkhtmltopdf is unmaintained: Your options in 2026](https://marqius.com/blog/wkhtmltopdf-deprecated-alternatives/) [Install wkhtmltopdf on Debian 12 or 13: Bookworm and Trixie](https://marqius.com/blog/install-wkhtmltopdf-debian/) [wkhtmltopdf vs Gotenberg: When a PDF API makes sense](https://marqius.com/blog/wkhtmltopdf-vs-gotenberg/) [All journal guides](https://marqius.com/blog/)

Source for this page [^official-page].

[^official-page]: https://marqius.com/blog/wkhtmltopdf-vs-headless-chromium/

[Browse this section](index.md) · [Knowledge index](../index.md)
