---
type: Article
title: Migrate Python pdfkit off wkhtmltopdf | Marqius
description: Keep Python pdfkit. Change the PDF program it starts and check one invoice.
resource: https://marqius.com/blog/migrate-python-pdfkit-off-wkhtmltopdf/
tags:
  - marqius
  - journal
status: stable
sources:
  - id: official-page
    resource: https://marqius.com/blog/migrate-python-pdfkit-off-wkhtmltopdf/
    last_modified: 2026-11-20T07:05:31.687Z
generated:
  by: process:marqius-site-build
  at: 2026-11-20T10:17:10.036Z
x_marqius:
  language: en
  source_sha256: f8615c45316a4eff0662944409d1df3150454ace4948a79298f4f33441331df8
  extraction: public-main-content
---

wkhtmltopdf migration

# Migrate Python pdfkit off wkhtmltopdf

Keep Python pdfkit. Change the PDF program it starts and check one invoice.

Marqius November 20, 2026

Your Python app has already worked out the tax and total for an invoice. It hands the finished page to pdfkit. If wkhtmltopdf is missing on the new server, that last step is where the job stops.

**Marqius is a drop-in replacement for wkhtmltopdf.** Your app can keep using Python pdfkit to ask for a PDF.

## Why this helps

Point pdfkit at Marqius and keep the Python code that builds the invoice. You can fix the missing PDF step without touching the code that calculates what the customer owes.

## Make your first PDF

Start with **Invoice 1001** for **120.00 EUR**. Open the example PDF to see what this library’s test should produce. The kit includes all 14 sample projects and a more detailed print demo for checking tables and page breaks. Open `START-HERE.html` after unzipping. [Download the library starter kit (ZIP)](https://marqius.com/download/wkhtmltopdf-demo/0.12.8/marqius-wrapper-demos.zip) · [Open the library example PDF](https://marqius.com/download/wkhtmltopdf-demo/0.12.8/expected-wrapper-invoice.pdf)

With Docker running, unzip the demo to a fresh folder and open a terminal in the folder containing `examples/`. You can also start in an empty folder. The command in step 3 will fetch the files for you inside the container.

### 1\. Open a fresh test container

Terminal

```
docker run --rm -it --mount "type=bind,source=$PWD,target=/proof" debian:bookworm-slim bash
```

Run the rest of the steps in the shell that just opened. The container is a fresh Linux test environment. Your host folder is mounted as `/proof`, so you can open the saved PDF after the test.

### 2\. Install the tools and Marqius

Terminal

```
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ca-certificates curl unzip fonts-dejavu-core poppler-utils python3 python3-venv
mkdir -p /work
cd /work
curl -fsSLo install-marqius.sh https://marqius.com/marqius-wkhtmltopdf.sh
bash install-marqius.sh --version 0.12.8 --prefix /work/bin
export PATH="/work/bin:$PATH"
export WKHTMLTOPDF_BINARY=/work/bin/marqius-wkhtmltopdf
"$WKHTMLTOPDF_BINARY" --version
wkhtmltopdf --version
```

The version output should include **marqius-wkhtmltopdf 0.12.8**. Marqius supplies the `wkhtmltopdf` command inside this test container.

### 3\. Bring the demo project into the test container

Terminal

```
cd /work
if [ -d /proof/examples/python-pdfkit ]; then
  cp -R /proof/examples .
else
  curl -fsSLo wrapper-demos.zip https://marqius.com/download/wkhtmltopdf-demo/0.12.8/marqius-wrapper-demos.zip &&
    unzip -oq wrapper-demos.zip
fi
```

### 4\. Install pdfkit in a Python environment

Terminal

```
python3 -m venv .venv
.venv/bin/python -m pip install -r examples/python-pdfkit/requirements.txt
```

### 5\. Make the invoice through pdfkit

Terminal

```
.venv/bin/python examples/python-pdfkit/render.py /proof/invoice.pdf
```

### 6\. Check that the PDF contains the right invoice

Terminal

```
pdfinfo /proof/invoice.pdf | grep '^Pages:'
pdftotext /proof/invoice.pdf - | grep -F 'Invoice 1001'
pdftotext /proof/invoice.pdf - | grep -F '120.00'
chmod a+r /proof/invoice.pdf
```

Look for one page, the invoice number and the amount. Type `exit` to close the test container. Open `invoice.pdf` in the folder you created on your computer.

## How to switch your own app to Marqius

Pass an absolute executable path to pdfkit.configuration and hand that configuration to the same from\_string, from\_file or from\_url call you already use.

Install Marqius alongside the original. Set `WKHTMLTOPDF_BINARY` in the application process to the new executable's full path unless the example specifies a framework-specific variable. The Debian APT package installs `/usr/bin/marqius-wkhtmltopdf`. [Debian installation guide](https://marqius.com/blog/install-wkhtmltopdf-debian/) · [Downloads for other environments](https://marqius.com/wkhtmltopdf/download/)

Apply the change in Python code where your app creates the pdfkit configuration. Retain the existing rendering options unless your comparison identifies a reason to change them.

python

```
import os
import pdfkit

config = pdfkit.configuration(wkhtmltopdf=os.environ['WKHTMLTOPDF_BINARY'])
pdfkit.from_string(html, 'invoice.pdf', configuration=config, options={'page-size': 'A4'})
```

## Try it with a document you know

Run the render from the web or background process that actually sends your invoices. Shell PATH and worker PATH can differ. For a long invoice, make sure the repeated headings, VAT totals and last row survive the page break.

If pdfkit says it cannot find an executable, set the variable in the service environment and check that the service user can execute that exact path. Preserve your existing options dictionary and CSS assets while you compare output.

## Check the old and new PDFs

Save a PDF from the old setup. Make it again with the same data and fonts. Check the words, amounts and page breaks. Keep the old program path handy so you can switch back if you need to. The [runnable Python pdfkit example](https://github.com/marqius-wkhtmltopdf/marqius-wkhtmltopdf-examples/tree/a76beedb20845e2ebec0c73741cee70d7142385a/examples/python-pdfkit/) exercises a sample PDF through the wrapper. The [developer manual chapter](https://marqius.com/download/developer-manual.pdf#page=7) records the test conditions and constraints. The [public comparison scoreboard](https://github.com/marqiushq/wkhtmltopdf-parity#the-scoreboard) reports differences for the wkhtmltopdf and Marqius renderers.

[All 14 library guides](https://marqius.com/blog/wkhtmltopdf-deprecated-alternatives/) · [django-wkhtmltopdf](https://marqius.com/blog/migrate-django-wkhtmltopdf/) · [Ruby PDFKit](https://marqius.com/blog/migrate-ruby-pdfkit-off-wkhtmltopdf/) · [Try Marqius for 30 days](https://marqius.com/wkhtmltopdf-buy/)

## Reader questions

### Do I need to replace the Python pdfkit package?

Keep pdfkit and pass a configuration object that points to the new executable. The separate converter needs to be installed in the environment where Python runs.

## 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 headless Chromium: What changes when you switch](https://marqius.com/blog/wkhtmltopdf-vs-headless-chromium/) [All journal guides](https://marqius.com/blog/)

Source for this page [^official-page].

[^official-page]: https://marqius.com/blog/migrate-python-pdfkit-off-wkhtmltopdf/

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