wkhtmltopdf migration

wkhtmltopdf is unmaintained: Your options in 2026

wkhtmltopdf is archived. Try Marqius as a drop-in replacement, compare Chromium, Gotenberg and WeasyPrint, and check your own PDF before switching.

Marqius

Two illustrated invoice proofs aligned with a brass rule on a green desk

Imagine it’s Monday morning. Your app has a batch of invoices to send, but a server update left it looking for a tool called wkhtmltopdf. The invoices and the code that makes them still work. The tool that turns them into PDFs is the part you need to replace.

Marqius is a drop-in replacement for wkhtmltopdf. If your app starts the old program through a library such as pdfkit, Snappy, wicked_pdf or Rotativa, you can usually keep that library, your code and your invoice templates. Install Marqius beside the old program and point the app at it. Then print the same invoice and check it before you switch the rest.

Why this helps

Replacing a PDF tool can sound like rewriting the part of your app that sends every invoice, statement or report. With a drop-in replacement, you start with the step that needs changing. The app still prepares the same document. Marqius takes over the job of turning it into a PDF. You can try the change in a test copy of the app and keep the old setting for an easy switch back.

Why apt install wkhtmltopdf fails on Debian 13

The wkhtmltopdf project was archived on 2 January 2023. See the original project on GitHub

Debian 12 Bookworm still offers wkhtmltopdf. Debian 13 Trixie dropped it because it relied on an old browser engine called QtWebKit. Why wkhtmltopdf became hard to maintain

A Docker build using debian:stable can move to Trixie when rebuilt. The same APT command then gives a different result. The standard Ubuntu 26.04 archive also listed no published package for amd64 or arm64 when checked on 20 November 2026. Ubuntu package search

On the machine or container where your app makes PDFs, run:

Terminal
. /etc/os-release
printf '%s\n' "$PRETTY_NAME"
command -v wkhtmltopdf || true
apt-cache policy wkhtmltopdf

If command -v wkhtmltopdf prints nothing, your shell can’t find the program. On Debian 12, refresh your package lists and check again if APT shows no version to install.

If your app moved to Debian 13, you can make one invoice with Marqius and check the PDF before changing the app. Get PDFs working again on Debian

Try Marqius with one invoice

Start with a small invoice you can share freely. You’ll check its number and total before touching the app your customers use. These steps use Docker and curl on Linux, macOS, or Windows with a WSL shell and Docker integration.

1. Get the sample invoice

Terminal
mkdir -p marqius-invoice-demo
cd marqius-invoice-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) · Open the 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

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. Make the PDF

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
ls -lh invoice-marqius.pdf

Open invoice-marqius.pdf from this folder. Check Invoice 1001, the three product lines and the 120.00 EUR total.

If you already have wkhtmltopdf installed, run the old tool with the same input and compare the PDFs:

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

An exit code reporting differences is useful. Open both PDFs to decide whether the changes are acceptable. You can also open our sample comparison with both original PDFs.

3. Change the setting in your app

The invoice still comes from the same template. The app changes which program it starts. For example, a Rails app using wicked_pdf can swap the path in its initializer after Marqius is installed at that path.

ruby
# Before
WickedPdf.configure { |config| config.exe_path = "/usr/bin/wkhtmltopdf" }

# After with the Marqius Debian package
WickedPdf.configure { |config| config.exe_path = "/usr/bin/marqius-wkhtmltopdf" }

Save the old setting. Print a real invoice from a test copy of your app and check the amounts, logo and page breaks before moving the live jobs. Try Marqius free for 30 days

Run the comparison with your own files

The comparison harness is MIT licensed. It runs both programs on the same HTML and fonts, with no network access for the render containers by default. You need Git and Docker for these commands. From your demo folder:

Terminal
git clone https://github.com/marqiushq/wkhtmltopdf-parity
cd wkhtmltopdf-parity
cp ../invoice.html mine/
printf '%s\n' '--page-size A4' > mine/options.txt
./run.sh mine

Open out/mine/report.html. You’ll get both PDFs and a report showing where they differ. To test one of your own documents, replace the sample HTML in mine/, include the fonts and images it needs, and write your app’s options in mine/options.txt. Run the last command again. Template setup notes

On 20 November 2026, Marqius 0.12.8 scored 0.9924 across 86 core documents against wkhtmltopdf 0.12.6. The score combines text, word positions and page count. Ink overlap is measured separately, and the full run includes other cases such as languages and CLI options. Scoreboard and method · This CI run

Latest results · Issue tracker · CI run history

Find the setting for your wrapper

A wrapper is the library your app uses to start the PDF program. Each guide runs a sample invoice before showing how to make the same change in your app.

Compare the five options

Tool

Status and how it runs

What happens to existing templates

JavaScript

How to check a switch

Marqius

Maintained proprietary command-line program

Keep your wrapper and template for a first test. Some flags or layouts can differ.

Limited in the native renderer. Test pages that depend on scripts.

Run both programs with the same files using the public harness above.

wkhtmltopdf

Archived command-line program

Keep your existing output as a baseline.

Old QtWebKit.

Save one of the PDFs your app already sends.

Headless Chromium

Maintained browser, controlled from a script or command

Map PDF options and check print CSS, headers and page breaks.

Browser JavaScript. Wait for the page to finish loading.

Print the same invoice in Chromium.

Gotenberg

Maintained open-source service, typically run in Docker

Send HTML over HTTP. Its HTML route uses Chromium, so check the print layout.

Browser JavaScript on Chromium routes.

Send the same invoice to a local test service.

WeasyPrint

Maintained open-source Python library and command

Test your print CSS. If JavaScript builds the page, prepare that HTML before sending it.

No browser JavaScript.

Render the same HTML and compare the pages.

If the app directly loads libwkhtmltox, plan an integration change. A new command by itself cannot replace a shared library. WeasyPrint documentation

Marqius publishes this guide. Start with the option that fits the way your app makes PDFs today.

Reader questions

Is wkhtmltopdf safe to keep using?

The upstream project is archived and no longer publishes fixes there. Its maintainer warns against converting HTML from untrusted sources. If you still rely on it, keep the job away from untrusted input while you plan and test the switch.

Why was wkhtmltopdf discontinued?

It depended on an old version of QtWebKit that became difficult to maintain. The upstream repository was archived in January 2023. Debian later removed the package from Trixie.

Can I install wkhtmltopdf on Debian 12 or Ubuntu 26.04?

Debian 12 Bookworm still has its own wkhtmltopdf package. The standard Ubuntu 26.04 archive had no published package for amd64 or arm64 when we checked. Run apt-cache policy wkhtmltopdf after apt-get update to see what your enabled sources offer.

What is the closest drop-in replacement for wkhtmltopdf?

If your app starts a wkhtmltopdf executable, Marqius is designed for that call. Point the wrapper at Marqius and check one PDF through the actual app. An integration that loads libwkhtmltox directly needs a separate change.

Is Gotenberg enough to replace wkhtmltopdf?

Gotenberg may fit if you want a shared service or also make PDFs from Office files. Apps that currently start wkhtmltopdf need to send a request to Gotenberg instead and check the new output.

Do I have to rewrite my templates?

With Marqius, start with the same templates. Check how your PDFs use fonts, scripts, headers and page breaks, then fix the differences that matter to your documents.