Installing Correct wkhtmltopdf for ERPNext v12 (Ubuntu 18.04)
Purpose
ERPNext v12 requires a patched version of wkhtmltopdf to correctly generate PDFs (Print Formats, Email Attachments, WhatsApp PDFs).
Using the default Ubuntu wkhtmltopdf will fail on headless servers.
This guide installs the exact version proven to work in production.
Supported Environment
| Component | Requirement |
|---|---|
| ERPNext | v12.x |
| Frappe | v12.x |
| OS | Ubuntu 18.04 (Bionic) |
| wkhtmltopdf | 0.12.5 (with patched qt) |
Common Symptoms (If Wrong Version Is Installed)
If wkhtmltopdf is incorrect, you will see:
Could not connect to any X display
wkhtmltopdf exited with non-zero code 1
using unpatched qt
Effects:
-
PDF download fails
-
Emails with attachments fail
-
Background jobs fail
-
WhatsApp PDF sending fails
Verify Current Version (Before Installing)
wkhtmltopdf --version
Wrong
wkhtmltopdf 0.12.4
Wrong (no patched qt)
wkhtmltopdf 0.12.6
Correct
wkhtmltopdf 0.12.5 (with patched qt)
Correct Installation Steps
Step 1: Remove Existing wkhtmltopdf
sudo apt remove wkhtmltopdf -y
Confirm removal:
which wkhtmltopdf
Expected: no output
Step 2: Download Correct Patched Package
cd /tmp
wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox_0.12.5-1.bionic_amd64.deb
Verify file:
ls -lh wkhtmltox_0.12.5-1.bionic_amd64.deb
Step 3: Install Package (Use apt, NOT dpkg)
sudo apt install ./wkhtmltox_0.12.5-1.bionic_amd64.deb -y
apt installis required to resolve dependencies properly.
Step 4: Verify Installation Path
The binary installs to:
/usr/local/bin/wkhtmltopdf
Verify:
/usr/local/bin/wkhtmltopdf --version
Expected:
wkhtmltopdf 0.12.5 (with patched qt)
Step 5: Create Required Symlinks (CRITICAL)
ERPNext expects wkhtmltopdf in /usr/bin.
sudo ln -s /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf
sudo ln -s /usr/local/bin/wkhtmltoimage /usr/bin/wkhtmltoimage
Verify:
wkhtmltopdf --version
Expected:
wkhtmltopdf 0.12.5 (with patched qt)
Step 6: Restart ERPNext Services
cd ~/frappe-bench
bench restart
Post-Installation Verification
Test 1: PDF Download
Open any print format:
/api/method/frappe.utils.print_format.download_pdf
PDF downloads successfully
No X display errors