---
type: Article
title: Migrate Rails wicked_pdf off wkhtmltopdf | Marqius
description: Keep your Rails views and wicked_pdf. Change the executable path
  and test the same report.
resource: https://marqius.com/blog/migrate-wicked-pdf-off-wkhtmltopdf/
tags:
  - marqius
  - journal
status: stable
sources:
  - id: official-page
    resource: https://marqius.com/blog/migrate-wicked-pdf-off-wkhtmltopdf/
    last_modified: 2026-11-20T07:05:59.318Z
generated:
  by: process:marqius-site-build
  at: 2026-11-20T10:17:10.036Z
x_marqius:
  language: en
  source_sha256: a5c8f03b0cf59394f18785d92b8cfc53fb0eecdd3dce38b578113d47ceb42288
  extraction: public-main-content
---

wkhtmltopdf migration

# Migrate Rails wicked\_pdf off wkhtmltopdf

Keep your Rails views and wicked\_pdf. Change the executable path and test the same report.

Marqius November 20, 2026

Your Rails app still shows the monthly report in the browser. When someone asks for a PDF, wicked\_pdf looks for wkhtmltopdf and can’t start it.

**Marqius is a drop-in replacement for wkhtmltopdf.** Your app can keep using Rails wicked\_pdf to ask for a PDF.

## Why this helps

Set the program path in one Rails initializer. Keep the report view and PDF call, then make the same report from a test copy of the app.

## 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:trixie-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 ruby ruby-bundler ruby-dev build-essential
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/wicked-pdf ]; 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 the Ruby gems for this example

Terminal

```
cd examples/wicked-pdf
bundle install
```

### 5\. Make the invoice through the gem

Terminal

```
bundle exec ruby render.rb /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

Set exe\_path in the Rails initializer. You can continue to render the same templates through wicked\_pdf while the application points at Marqius.

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 config/initializers/wicked\_pdf.rb. Retain the existing rendering options unless your comparison identifies a reason to change them.

ruby

```
WickedPdf.configure do |config|
  config.exe_path = ENV.fetch('WKHTMLTOPDF_BINARY')
end
```

## Try it with a document you know

Render a report with the same Rails layout, asset helpers and header options. Use the staging build so fingerprinted CSS and images are resolved exactly as they are for your users.

If deployment also uses a wkhtmltopdf binary gem, confirm Rails actually receives the explicit exe\_path and can execute it. Restart your Rails app and jobs after updating the initializer or environment.

## 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 Rails wicked\_pdf example](https://github.com/marqius-wkhtmltopdf/marqius-wkhtmltopdf-examples/tree/a76beedb20845e2ebec0c73741cee70d7142385a/examples/wicked-pdf/) exercises a sample PDF through the wrapper. The [developer manual chapter](https://marqius.com/download/developer-manual.pdf#page=29) 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/) · [Ruby PDFKit](https://marqius.com/blog/migrate-ruby-pdfkit-off-wkhtmltopdf/) · [Python pdfkit](https://marqius.com/blog/migrate-python-pdfkit-off-wkhtmltopdf/) · [Try Marqius for 30 days](https://marqius.com/wkhtmltopdf-buy/)

## Reader questions

### What if a binary gem currently supplies wkhtmltopdf?

Set the Rails initializer to the Marqius executable explicitly so you can evaluate it alongside the gem. Keeping the original environment makes rollback a configuration change.

## 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-wicked-pdf-off-wkhtmltopdf/

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