Common problems and fixes for wkhtmltopdf in Odoo

If you're trying to do any HTML to PDF conversion in Odoo, you're likely to use wkhtmltopdf. At Transformy we love this library and I think it's a great fit for many use cases. You can find my detailed guide on how to use whktmltopdf here.

Unfortunately, installing and getting it to work with Odoo it isn't obvious and there's a few pitfalls you need to avoid. In this guide I'm going to cover some common errors and their solutions to hopefully save you time debugging wkhtmltopdf.

Unable to find wkhtmltopdf

Let's start with an easy one.

If you're seeing "Unable to find Wkhtmltopdf on this system", it means the server cannot locate the wkhtmltopdf binary. This usually happens after a fresh Odoo installation or migrations where wkhtmltopdf wasn't properly configured.

Linux Installation Issues

On Linux, the wkhtmltopdf command must be in a directory accessible by Odoo's PATH variable. To solve this issue, create a symlink from /usr/local/bin/wkhtmltopdf to /usr/bin, or add /usr/local/bin to Odoo's PATH.

Windows Configuration Requirements

The Odoo all-in-one Windows installer comes with the wkhtmltopdf that should work out of the box. If you went with a manual installation of Odoo, some additional configuration is required:

1. Download the wkhtmltopdf installer
2. In older Odoo versions (8-14), set the webkit_path system parameter to the full path of wkhtmltopdf.exe
3. Add the wkhtmltopdf bin directory (e.g., C:\Program Files\wkhtmltopdf\bin) to the Windows PATH
4. Restart the Odoo service

For Odoo 15+, the webkit_path parameter is optional if wkhtmltopdf is in the PATH variable or configured in your odoo.conf file.

Wrong wkhtmltopdf Version

A lot of wkhtmltopdf errors happen because of incompatible versions. This can lead to issues like missing headers or footers, overlapping text, font size issues, or completely blank PDFs. Each Odoo version requires a specific wkhtmltopdf version.

Version Compatibility Issues

Some known issues that occur because of version incompatibility are:

• Odoo 8: wkhtmltopdf 0.12.2.1 causes fonts to enlarge and overlap. Downgrading to 0.12.1 resolves the issue
• Odoo 13: wkhtmltopdf 0.12.4 can cause missing headers and footers in PDF reports. Upgrading to 0.12.5 resolves the issue
• Odoo 17: wkhtmltopdf 0.12.6 produces PDFs without logos or footers. Upgrading to the patched 0.12.6.1 build fixes the issue

Just to be clear Odoo needs the patched Qt version of wkhtmltopdf. Running wkhtmltopdf --version should show "(with patched qt)" in the output.

Installation Commands:

A common mistake is using a package manager to install wkhtmltopdf (crazy idea, I know.) By running sudo apt-get install wkhtmltopdf you will end up with the unpatched version mentioned earlier.

Here's how to install the patched version:

# Correct installation for Odoo 17 on Ubuntu:
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6.1-3.jammy_amd64.deb

Missing Dependencies on New OS Versions

Newer Linux distributions often lack libraries required by recommended wkhtmltopdf versions. This issue particularly affects Ubuntu 22.04+ and other modern distributions that have removed older SSL libraries.

Ubuntu 22.04+ libssl1.1 Issue

When installing wkhtmltopdf 0.12.5 on Ubuntu 22.04 or newer, you might encounter this error:

dpkg: dependency problems prevent configuration of wkhtmltox:
 wkhtmltox depends on libssl1.1; however:
  Package libssl1.1 is not available

Ubuntu 22.04 removed libssl1.1, but wkhtmltopdf 0.12.5 still depends on it. There are two solutions:

1. Use wkhtmltopdf 0.12.6.1 (patched) built specifically for Ubuntu 22.04 ("Jammy"). This version includes updated dependencies.
2. Manually install libssl1.1 from Ubuntu 20.04 repositories. This is a bit more tricky and I'd recommend going with the #1 option

Missing report.url

Another common problem is not setting the report.url parameter. Without this parameter, assets like logos, images, or stylesheets are not sent correctly to wkhtmltopdf. This can lead to a variety of issues with the generated PDFs:

• missing images
• blank header and/or footer sections

Why report.url is Critical

The report.url parameter must match the URL where your Odoo instance is reachable. For example, in Odoo 17, users printing invoices locally see no logo or footer until they add this parameter. The issue affects all Odoo versions when wkhtmltopdf needs to fetch resources.

Configuration Steps:

1. Navigate to Settings → Technical → Parameters → System Parameters
2. Create a new parameter:
   • Key: report.url
   • Value: http://localhost:8069 (or your Odoo URL)

Runtime errors

There are a few error codes that come up regularly. I've listed the most common ones along with the solution.

Error Code -11: Segmentation Fault

Exit code -11 indicates a wkhtmltopdf process crash (segfault). This error has multiple documented causes:

Resource Limit Issues

The most common cause is exceeding file handle limits when generating large reports. Each page with a header/footer causes wkhtmltopdf to open those resources repeatedly. This tends to happen when you're trying to generate PDFs with a large number of pages.

Proven Solutions:

# Check current file handle limit
ulimit -n

# Increase limit in Odoo startup script
ulimit -n 10000

It's also worth trying to increase limit_memory_hard in Odoo configuration to avoid memory-related crashes.

Error Code -6: Abnormal Termination

Another error that is often encountered in newer Odoo (16 or 17) versions is error -6 (signal 6, abort)

This is again related to a wkhtmlversion mismatch, and solved by removing 0.12.6 and installing wkhtmltox_0.12.6.1-3.jammy_amd64.deb.

Error Code -9: Process Killed (SIGKILL)

Error -9 means the wkhtmltopdf process was killed by Odoo's safety limits. This happens when a report exceeds limit_time_real or consumes excessive memory.

Exit with code 1 due to network error: TimeoutError

This error means wkhtmltopdf tried to load a resource (image, CSS, etc.) and failed due to network timeout. This often indicates a missing or incorrect report.url configuration.

PATH variable issues

Even with wkhtmltopdf installed, Odoo must have proper permissions and PATH configuration to execute it. There are a bunch of errors you'll run into if both of these aren't set up correctly.

Linux PATH Configuration

When wkhtmltopdf is installed in /usr/local/bin it will not be accessible because Odoo's service only has /usr/bin in its PATH.

This can be solved by adding PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin to the Odoo startup script.

Permission and Security Issues

• Ensure the Odoo user has execute permissions for the wkhtmltopdf binary
• Watch out for SELinux blocking wkhtmltopdf from launching.

PDF formatting

wkhtmltopdf relies on system fonts. Missing fonts cause fallback to defaults, altering layouts.

There are multiple reports on the Odoo forums from people complaining their layout looks off or has shifted. In some cases this is due to fonts missing on the production environment.

Try either installing the missing font on your server or switching to a default system font in the HTML you're trying to convert.

CSS Limitations

wkhtmltopdf uses Qt WebKit from 2013 which isn't maintained anymore and doesn't support all CSS features:

• No flexbox or grid support
• Limited CSS3 selectors
• Some properties ignored

There's not really any workarounds for this if you want to keep using wkhtmltopdf other than changing and simplifying your HTML/CSS.

Page Break Challenges

CSS like page-break-before: always or page-break-inside: avoid works inconsistently. Forum users report JavaScript-based page breaks often fail.

Best Practices:

• Structure QWeb templates with explicit page-break divs
• Use page-breaking CSS on block elements
• For tables, ensure rows aren't set to "avoid break"
• Test incrementally

Performance issues

A lot of people complain about slow PDF generation with wkhtmltopdf. The most common reasons why this might happen are:

• High-resolution images
• Multiple webfont files
• Large CSS files
• Heavy JavaScript pages

The solution to all of these is quite obvious, but I'd say that the biggest win is removing custom fonts since it can significantly reduce PDF generation time.

Troubleshooting table

Here's a summary table of the most common wkhtmltopdf issues for HTML to PDF conversion. If you run into any other problems (and fixes) not listed here, shoot us a message.