Odoo wkhtmltopdf Errors, Exit Codes and Fixes

Odoo still uses wkhtmltopdf for many PDF reports, but wkhtmltopdf is now archived and remains in Odoo mainly as a legacy dependency. If you cannot migrate immediately, the fixes below cover missing binaries, patched Qt builds, report.url, exit codes, missing assets, and CSS limitations. For command basics, see the wkhtmltopdf tutorial.

Installing and running the correct build in Odoo is not obvious. This guide keeps the working fixes for existing installations while you plan a longer-term move; the Odoo wkhtmltopdf migration guide covers that path.

Unable to find wkhtmltopdf on this system

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.

Choosing the correct wkhtmltopdf build for each Odoo 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.

Odoo and wkhtmltopdf compatibility table

Last reviewed: August 2026. These are legacy compatibility recommendations for existing Odoo deployments.

Why Odoo needs wkhtmltopdf with patched Qt

Odoo needs the patched Qt version of wkhtmltopdf for headers, footers, and other report options. Running wkhtmltopdf --version should show “(with patched qt)” in the output.

Installation Commands:

A common mistake is using a distribution package manager to install wkhtmltopdf. Running sudo apt-get install wkhtmltopdf can install an unpatched Qt build that does not support Odoo's headers and footers correctly.

Legacy installation command, reviewed August 2026: Use this only for an existing compatible Odoo deployment on Ubuntu 22.04. Confirm the package, architecture, and Odoo version before installing it.

# Legacy patched-Qt build for Odoo 16+ on Ubuntu 22.04 (amd64):
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

Ubuntu 22.04, 24.04, and 25.04 package problems

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. For Odoo 16 and later on Ubuntu 22.04, use the compatible 0.12.6.1 patched build shown above instead of forcing the old dependency.

Ubuntu 24.04 provides a repository build, but it is not built with Odoo's patched Qt. Ubuntu 25.04 is also past standard support. On either release, do not copy libssl1.1 from an older Ubuntu repository just to satisfy wkhtmltopdf. Use an Odoo-supported image or package for your exact release, or move PDF rendering to a maintained engine.

Missing report.url in Odoo

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.

Exit code -11 and QPaintDevice: Cannot destroy paint device that is being painted

Exit code -11 indicates a wkhtmltopdf process crash (segfault). The same failure can include QPaintDevice: Cannot destroy paint device that is being painted in the log. 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.

Missing fonts, logos, headers, and footers

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. For missing logos, headers, or footers, also verify report.url and confirm that your wkhtmltopdf version includes patched Qt.

CSS, flexbox, grid, and page-break 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.

If you only need to stabilize an existing installation, these fixes can keep the legacy report path running temporarily. If the failures come from unsupported CSS, JavaScript, or operating-system dependencies, compare maintained alternatives to wkhtmltopdf. Transformy's HTML-to-PDF API is a managed Headless Chrome option when you want Odoo to delegate PDF rendering.

Frequently asked questions

How do I fix “Unable to find Wkhtmltopdf on this system” in Odoo?

Make sure the binary is installed, executable by the Odoo service user, and available in that service's PATH. Restart the Odoo service after changing the path.

Which wkhtmltopdf version should I use with Odoo?

Use 0.12.1 for Odoo 9 and earlier, 0.12.5-1 for Odoo 10–15, and the patched 0.12.6.1-3 build for Odoo 16 and later. Confirm that wkhtmltopdf --version includes “with patched qt.”

How do I fix Odoo wkhtmltopdf exit code -6?

Check for a version mismatch or an unpatched Qt build first. On Odoo 16 and later, replace the plain 0.12.6 build with the compatible patched 0.12.6.1 package for your operating system.

What causes exit code -11 and the QPaintDevice error?

Both indicate that wkhtmltopdf crashed. Check file-handle and memory limits, verify the patched build, and test a smaller report without repeated headers and footers to isolate resource pressure.

Why are fonts, logos, headers, or footers missing from an Odoo PDF?

Missing assets usually point to an incorrect report.url, inaccessible asset URLs, missing server fonts, or an unpatched or incompatible wkhtmltopdf build.