| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Lines of code | 1025 |
| Technical Name |
chrome_pdf_engine |
| License | OPL-1 |
| Versions | 17.0 18.0 19.0 |
Chrome Headless
PDF Engine for Odoo
Replace the unmaintained wkhtmltopdf with the power of modern Google Chrome — full HTML5, CSS3, and pixel-perfect PDFs, right inside Odoo.
wkhtmltopdf is Dead. Your PDFs Deserve Better.
wkhtmltopdf hasn't had a meaningful release since 2020. It's built on an ancient WebKit engine, lacks support for modern CSS, and breaks silently on complex reports. Meanwhile, your users expect pixel-perfect invoices, delivery slips, and reports.
| Capability | wkhtmltopdf | Chrome Headless PDF Engine |
|---|---|---|
| HTML5 & CSS3 (full spec) | ⚠ Partial (old WebKit) | ✓ Complete |
| CSS Grid Layout | ✗ Not supported | ✓ Full support |
| CSS Flexbox | ⚠ Broken in many cases | ✓ Full support |
| CSS Custom Properties (vars) | ✗ Not supported | ✓ Full support |
| SVG rendering | ⚠ Partial, often garbled | ✓ Perfect |
| Unicode & Emoji | ⚠ Limited, font-dependent | ✓ Full |
| Web Fonts (@font-face) | ⚠ Unreliable | ✓ Reliable |
| Header / Footer with page numbers | ⚠ Hack-dependent | ✓ Native CDP support |
| Print CSS (@media print, @page) | ⚠ Partial | ✓ Full |
| Active maintenance | ✗ Abandoned since 2020 | ✓ Backed by Google |
| Security patching | ✗ No updates | ✓ Continuous (Chrome releases) |
| Large report performance | ⚠ Memory leaks on big jobs | ✓ Stable, process-isolated |
Everything You Need, Nothing You Don't
A focused, production-grade replacement — no bloat, no SaaS accounts, no API keys.
Pixel-Perfect PDF Output
Chrome renders your QWeb templates exactly as they appear in a browser — what you design is what gets printed.
Chrome DevTools Protocol
Uses CDP over WebSocket — the same low-level protocol used by Puppeteer and Playwright — for reliable, scriptable rendering.
Drop-in Replacement
Overrides ir.actions.report seamlessly. No template changes needed. Every existing report works out of the box.
Configurable via Settings UI
Set the Chrome binary path, timeout, fallback behavior, and extra flags from Settings → General Settings. No file edits.
Parallel PDF Generation
Each render job uses an isolated Chrome process on a dedicated port — safe for multi-worker Odoo deployments.
Automatic Fallback
Optionally fall back to wkhtmltopdf if Chrome is unavailable, so your Odoo instance never goes down because of a missing binary.
Runs Fully On-Premise
No external service, no internet call, no API key. All rendering happens on your own server — your documents never leave.
Rich Header & Footer
Pass any HTML as header/footer templates with live page number, total pages, date, title, and URL injected by Chrome natively.
All Paper Formats
A0–A6, Letter, Legal, Tabloid, Ledger, custom dimensions in inches, portrait and landscape — all configurable per report.
How It Works
A lightweight, pure-Python pipeline that spawns Chrome, communicates over WebSocket, and returns PDF bytes — no external services involved.
Odoo QWeb Report Request │ ▼ ir.actions.report._run_wkhtmltopdf() ← method is overridden │ ▼ IrActionsReport._run_chrome_headless() │ ├─ _build_chrome_print_options() ← paperformat → CDP params ├─ _build_chrome_html() ← full HTML document assembly │ ▼ ChromePDFPrinter.html_to_pdf() ← chrome_cdp.py │ ├─ ChromeProcess.start() ← spawns headless Chrome subprocess ├─ ChromeProcess.get_ws_url() ← POST /json/new → WebSocket URL │ ▼ ChromeCDPClient (ws://127.0.0.1:PORT) │ ├─ Page.enable ├─ Page.navigate → about:blank ├─ Page.setDocumentContent ├─ [wait for Page.loadEventFired] └─ Page.printToPDF → base64 PDF bytes
Installation in 3 Steps
Most servers already have Chrome or Chromium available. Setup takes under 5 minutes.
Install Chrome or Chromium on your server
Any modern Chromium-based browser (Chrome 112+ recommended for --headless=new mode).
Install the Python WebSocket client
The only non-stdlib dependency — a pure-Python WebSocket library.
Install & activate the Odoo module
Copy to your addons path and install via the Apps menu, or use the CLI:
Then open Settings → General Settings → Chrome PDF Engine to verify Chrome was found automatically.
--no-sandbox,--disable-setuid-sandbox to the Extra Chrome Flags field in Settings. These flags are required when Chrome runs without a user namespace (root or unprivileged container).
Simple, Transparent Settings
All options are exposed in Settings → General Settings and stored as Odoo System Parameters — no config file edits needed.
| Parameter Key | Default | Description |
|---|---|---|
| chrome_pdf.enabled | 1 (on) | Master switch — disable to revert all reports to wkhtmltopdf instantly. |
| chrome_pdf.binary_path | auto-detect | Explicit path to the Chrome/Chromium binary. Leave blank for automatic detection across common install locations. |
| chrome_pdf.timeout | 120 s | Maximum time Chrome is allowed per PDF render. Increase for very large or complex reports. |
| chrome_pdf.fallback | 0 (off) | When enabled, a failed Chrome render silently falls back to wkhtmltopdf instead of raising an error. |
| chrome_pdf.extra_args | (empty) | Comma-separated extra CLI flags passed to Chrome at startup. Example: --no-sandbox,--proxy-server=http://proxy:3128 |
Supported Odoo Versions
The module ships branches for each major Odoo version. Install the branch that matches your Odoo installation.
- Python 3.8+
websocket-client(pip package)- Google Chrome 112+ or Chromium 112+ on the server
- Odoo modules:
base,web
Common Issues & Fixes
🔍 Chrome binary not found
Run which chromium-browser google-chrome to locate Chrome, then paste the full path into Settings → chrome_pdf.binary_path.
🔌 websocket-client not installed
Run pip install websocket-client inside the same Python environment that runs Odoo, then restart the server.
⏳ Large reports timing out
Increase chrome_pdf.timeout (e.g. to 300 seconds) in System Parameters for reports with many pages or heavy images.
🆕 Fonts rendering as boxes
Install system fonts: sudo apt-get install fonts-liberation fonts-noto fonts-dejavu-core, then restart Chrome.
🔒 Chrome crashes in Docker
Add --no-sandbox,--disable-setuid-sandbox to chrome_pdf.extra_args. Required for root/unprivileged container environments.
🌐 Behind a corporate proxy
Add --proxy-server=http://your-proxy:3128 to chrome_pdf.extra_args so Chrome can reach fonts or external resources.
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module