---
type: Article
title: Switch go-wkhtmltopdf to the Marqius executable | Marqius
description: Point the Go library at Marqius at startup. Keep the pages and
  options you already use.
resource: https://marqius.com/blog/migrate-go-wkhtmltopdf/
tags:
  - marqius
  - journal
status: stable
sources:
  - id: official-page
    resource: https://marqius.com/blog/migrate-go-wkhtmltopdf/
    last_modified: 2026-11-20T07:06:10.969Z
generated:
  by: process:marqius-site-build
  at: 2026-11-20T10:17:10.036Z
x_marqius:
  language: en
  source_sha256: 33d94fb86eff15b0652bd10ccdc0548cf4a863eb9be45ae0b298d3e4fb1d60db
  extraction: public-main-content
---

wkhtmltopdf migration

# Switch go-wkhtmltopdf to the Marqius executable

Point the Go library at Marqius at startup. Keep the pages and options you already use.

Marqius November 20, 2026

A Go service turns order data into a shipping PDF. It works on a developer’s laptop, but the deployed service can’t find the program it relies on.

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

## Why this helps

Give the Go library a known path when the service starts. Keep the code that adds pages and writes the shipping PDF, then test it in the same image you deploy.

## 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" golang:1.25-bookworm 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
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/go-wkhtmltopdf ]; 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\. Fetch the Go library

Terminal

```
cd examples/go-wkhtmltopdf
go mod tidy
```

### 5\. Build and run the Go invoice example

Terminal

```
go run . /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

Call wkhtmltopdf.SetPath during Go process startup, before creating a PDF generator. Keep your existing PDFGenerator options and pages.

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 Go startup code using github.com/SebastiaanKlippert/go-wkhtmltopdf. Retain the existing rendering options unless your comparison identifies a reason to change them.

go

```
wkhtmltopdf.SetPath(os.Getenv("WKHTMLTOPDF_BINARY"))
pdfg, err := wkhtmltopdf.NewPDFGenerator()
```

## Try it with a document you know

Keep normal error handling for generator creation and rendering. Validate your configured path at startup. Run the same `NewPageReader` or URL-based job under the deployed image and check document order, page size and output text.

Set the path once per process. When you compare two binaries concurrently, run the baseline and candidate in separate processes so a process-wide setting cannot mix the results.

## 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 go-wkhtmltopdf example](https://github.com/marqius-wkhtmltopdf/marqius-wkhtmltopdf-examples/tree/a76beedb20845e2ebec0c73741cee70d7142385a/examples/go-wkhtmltopdf/) exercises a sample PDF through the wrapper. The [developer manual chapter](https://marqius.com/download/developer-manual.pdf#page=35) 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/) · [Node.js wkhtmltopdf](https://marqius.com/blog/migrate-node-wkhtmltopdf/) · [Java wkhtmltopdf wrapper](https://marqius.com/blog/migrate-java-wkhtmltopdf-wrapper/) · [Try Marqius for 30 days](https://marqius.com/wkhtmltopdf-buy/)

## Reader questions

### When should Go code call SetPath?

Set it during startup before calling NewPDFGenerator, using the complete path inside the environment where the Go service 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-go-wkhtmltopdf/

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