---
type: Article
title: Migrate Laravel Snappy off wkhtmltopdf | Marqius
description: Keep your Blade template and invoice job. Update the PDF program
  used by Laravel Snappy.
resource: https://marqius.com/blog/migrate-laravel-snappy-off-wkhtmltopdf/
tags:
  - marqius
  - journal
status: stable
sources:
  - id: official-page
    resource: https://marqius.com/blog/migrate-laravel-snappy-off-wkhtmltopdf/
    last_modified: 2026-11-20T07:05:43.953Z
generated:
  by: process:marqius-site-build
  at: 2026-11-20T10:17:10.036Z
x_marqius:
  language: en
  source_sha256: d5c195fd699ee62b669d2e65516042de5a4a6cdade6d711d2a0315dba1886fd0
  extraction: public-main-content
---

wkhtmltopdf migration

# Migrate Laravel Snappy off wkhtmltopdf

Keep your Blade template and invoice job. Update the PDF program used by Laravel Snappy.

Marqius November 20, 2026

A Laravel app takes orders in the browser and prints invoices in the background. After an update, the orders come through, but the queue keeps failing on the PDF step.

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

## Why this helps

Set the new program path where Laravel already reads it. You can keep the Blade invoice and the queued job, then check that the background worker picked up the change.

## 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 php-cli composer php-mbstring php-xml php-curl php-zip php-sqlite3
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
export COMPOSER_ALLOW_SUPERUSER=1
"$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/laravel-snappy ]; 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\. Start a small Laravel app and add Snappy

Terminal

```
composer create-project laravel/laravel laravel-demo '^12.0' --no-interaction --prefer-dist
cd laravel-demo
composer require barryvdh/laravel-snappy --no-interaction --prefer-dist
```

### 5\. Give Snappy the new program and run the invoice job

Terminal

```
cp ../examples/laravel-snappy/render.php .
WKHTML_PDF_BINARY="$WKHTMLTOPDF_BINARY" php render.php /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 WKHTML\_PDF\_BINARY for the Laravel Snappy PDF configuration. Rebuild the configuration cache and restart persistent PDF workers as part of the rollout.

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 The Laravel application's environment, commonly its .env file. Retain the existing rendering options unless your comparison identifies a reason to change them.

dotenv

```
WKHTML_PDF_BINARY=/usr/bin/marqius-wkhtmltopdf
```

## Try it with a document you know

If config/snappy.php is customized, confirm that pdf.binary reads WKHTML\_PDF\_BINARY. Run `php artisan config:cache` if your deployment caches configuration. Submit a real queued invoice job and check that it uses the updated deployment.

If new web requests work while background PDFs still use the old binary, restart persistent queue workers through your usual deployment process. Check the environment in the queue container as well as the web container.

## 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 Laravel Snappy example](https://github.com/marqius-wkhtmltopdf/marqius-wkhtmltopdf-examples/tree/a76beedb20845e2ebec0c73741cee70d7142385a/examples/laravel-snappy/) exercises a sample PDF through the wrapper. The [developer manual chapter](https://marqius.com/download/developer-manual.pdf#page=18) 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/) · [KnpLabs Snappy](https://marqius.com/blog/migrate-snappy-off-wkhtmltopdf/) · [Symfony KnpSnappyBundle](https://marqius.com/blog/migrate-symfony-knp-snappy-bundle/) · [Try Marqius for 30 days](https://marqius.com/wkhtmltopdf-buy/)

## Reader questions

### Why does Laravel still use the old path after I edit .env?

A cached configuration or long-running queue worker may retain the old value. Rebuild the configuration cache and restart the workers that render PDFs.

## 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-laravel-snappy-off-wkhtmltopdf/

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