Install/Fix wkhtmltopdf Issue on macOS for Odoo | Step-by-Step guide

How to Install wkhtmltopdf on macOS for Odoo Users (Apple Silicon Compatible)

If you are using Odoo on a Mac with an Apple Silicon chip (M1, M2, or M3), you might have noticed that generating PDF reports doesn’t work out of the box. The common issue is that wkhtmltopdf, the utility Odoo relies on for rendering reports into PDFs, isn’t natively built for ARM-based Macs.

This guide explains how to install wkhtmltopdf properly on macOS so Odoo can generate PDF reports without errors.

Why wkhtmltopdf Is Important for Odoo

Odoo uses wkhtmltopdf to convert HTML templates into PDF reports. It powers features like printing invoices, quotations, sales orders, and other documents.

Without it, you’ll likely see errors such as:

wkhtmltopdf: command not found

or

zsh: bad CPU type in executable

The reason? The official wkhtmltopdf build for macOS is compiled for Intel (x86_64) processors, while your Apple Silicon Mac uses ARM (arm64).

To fix this, we need a bridge — that’s where Rosetta 2 comes in.

What Is Rosetta 2?

Rosetta 2 is Apple’s built-in translation layer that lets you run Intel-based applications on Apple Silicon Macs.

Think of it as a smart interpreter that automatically translates older Intel instructions into ARM instructions so apps like wkhtmltopdf can run seamlessly.

You don’t interact with Rosetta directly — it just ensures that Intel-only tools run without issues.

Step-by-Step Installation Guide

Follow these steps carefully to install wkhtmltopdf on macOS for Odoo.

Step 1: Install Rosetta 2

Run the following command in Terminal to install Rosetta:

softwareupdate --install-rosetta --agree-to-license

If Rosetta is already installed, the system will notify you, and you can proceed to the next step.

Step 2: Run Terminal in Rosetta Mode

To ensure wkhtmltopdf installs correctly under Intel emulation:

1. Open Finder → Applications → Utilities
2. Right-click Terminal.app → Get Info
3. Check the box “Open using Rosetta”
4. Close the window
5. Quit and reopen Terminal

Now confirm Terminal is running under Rosetta:

uname -m

It should return:

x86_64

If it shows arm64, double-check the Rosetta checkbox.

Step 3: Install wkhtmltopdf (.pkg File)

Download the macOS package (for example, wkhtmltox-0.12.6-2.macos-cocoa.pkg) and place it in your Downloads folder.

Then run this command:

sudo installer -pkg ~/Downloads/wkhtmltox-0.12.6-2.macos-cocoa.pkg -target /

This installs wkhtmltopdf globally to /usr/local/bin.

Step 4: Verify Installation

Check if it’s properly installed:

which wkhtmltopdf

Expected output:

/usr/local/bin/wkhtmltopdf

Then verify the version:

wkhtmltopdf --version

You should see:

wkhtmltopdf 0.12.6 (with patched qt)

Step 5: Make It Accessible System-Wide

Some Odoo setups (especially if installed via Homebrew) may not automatically find wkhtmltopdf.

You can fix that with symbolic links:

sudo ln -s /usr/local/bin/wkhtmltopdf /opt/homebrew/bin/wkhtmltopdf 2>/dev/null
sudo ln -s /usr/local/bin/wkhtmltoimage /opt/homebrew/bin/wkhtmltoimage 2>/dev/null

If the paths already exist, these commands will silently do nothing.

Step 6: Test PDF Generation

To confirm that wkhtmltopdf works correctly, run:

wkhtmltopdf https://www.google.com test.pdf

You should see a new file test.pdf created in your current directory.

If this works, the installation is successful.

Step 7: Configure Odoo

Next, make sure Odoo uses the correct wkhtmltopdf path.

Open your Odoo configuration file (for example, odoo.conf or /etc/odoo.conf) and add or update this line:

wkhtmltopdf = /usr/local/bin/wkhtmltopdf

Then restart Odoo:

sudo systemctl restart odoo

or restart it using your preferred method (e.g., via Docker or terminal command).

Step 8: (Optional) Switch Terminal Back

Once wkhtmltopdf is installed, you can switch Terminal back to native mode:

1. Go to Applications → Utilities → Terminal.app → Get Info
2. Uncheck “Open using Rosetta”

wkhtmltopdf will continue to run through Rosetta automatically — you don’t need to reinstall anything.

Quick Summary

Hope it Helps!

wkhtmltopdf is a critical dependency for Odoo’s reporting engine, and installing it correctly on macOS with Apple Silicon ensures that all PDF reports render flawlessly.

Once configured, you won’t have to touch it again — it runs smoothly behind the scenes, keeping your Odoo environment fully capable of generating invoices, reports, and all other documents.