What is wkhtmltopdf in Odoo

Introduction

In Odoo, one of the most frequent business requirements is generating professional, print‑ready PDF documents — invoices, quotations, delivery orders, purchase orders, and more. Behind many of these PDF outputs, wkhtmltopdf plays an important role. 

While most Odoo users and developers focus heavily on report templates and layout design, few realize that understanding how wkhtmltopdf works can save hours of debugging when reports suddenly look broken, misaligned, or inconsistent between environments.

What is wkhtmltopdf?

wkhtmltopdf is an open‑source command‑line tool that converts HTML web pages into PDF documents. It uses the WebKit rendering engine (the same engine that powers browsers like Safari and older versions of Chrome), which means it interprets HTML and CSS very similarly to a real browser — then transforms the rendered page into a printable PDF file.

How Odoo Uses wkhtmltopdf?

In Odoo, most printable reports are generated using three layers: 

1. QWeb Templates – XML/HTML structure defining the report’s content and logic. 
2. CSS Styles – Controls design, spacing, fonts, colors, borders, and page layout. 
3. wkhtmltopdf – The engine that converts the fully rendered QWeb output into a final PDF.

Why wkhtmltopdf Matters

• PDF Quality Depends Entirely on it

You might have a report that looks flawless in the browser preview (using Odoo’s built‑in HTML view). But the final PDF — generated via wkhtmltopdf — can look completely different. Why? Because wkhtmltopdf has its own rendering quirks, separate from your modern browser.

• Version Compatibility is Critical

Different versions of wkhtmltopdf behave differently. Using an unsupported or mismatched version can lead to: 

• • Blank PDF files (the most frustrating issue) 
  • Missing logos or images (often due to URL or permission problems) 
  • Incorrect fonts or fallback fonts 
  • Crashes during report printing 
  • Footers/headers not appearing
    

Odoo works best with specific wkhtmltopdf versions. For example, Odoo 15+ officially recommends wkhtmltopdf 0.12.6 (with patched Qt). Using version 0.12.5 may work, but 0.12.4 often causes blank PDFs.

How to Install wkhtmltopdf in Odoo

For Ubuntu/Debian 

Step 1: Download the correct package (example for Odoo 15/16/17 using wkhtmltopdf 0.12.6.1 with patched)

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb

sudo apt update
sudo apt install -y xfonts-75dpi xfonts-base fontconfig libjpeg-turbo8

sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb || true
sudo apt --fix-broken install -y

After that check if it has been success installed 

wkhtmltopdf --version

For windows or server you can visit the official wkhtmltopdf website or utilize package managers to download and install the appropriate version.

Conclusion

wkhtmltopdf is not glamorous, but it is one of the most critical dependencies in Odoo's reporting stack. Many Odoo users spend hours debugging broken PDF reports — only to discover the root cause was an incorrect or missing wkhtmltopdf installation. 

Key insight: 

1. wkhtmltopdf converts HTML to PDF – It's the engine behind Odoo's invoices, quotations, and delivery orders. 
2. Version matters enormously – Using the wrong version causes blank PDFs, missing images, and crashes. Always use the patched Qt version recommended for your Odoo release. 
3. Installation is straightforward – Whether on Ubuntu, Windows, or macOS, follow the steps above to install and verify wkhtmltopdf correctly. 
4. Debugging becomes easier – Once you understand wkhtmltopdf's quirks, you can quickly identify whether a report issue is in your QWeb code or in the PDF conversion layer. 
5. Prevention is better than cure – Set up wkhtmltopdf correctly from day one, and you'll avoid countless headaches later.