Installation & PDF Rendering Requirements

This page explains the two PDF rendering paths supported by Report Designer, their server requirements and the checks that should be completed before a production rollout.

Applies to: Odoo 19, mg_report_hub 19.0.7.1.64 and the optional mg_report_render extension 19.0.0.1.1.

1. Choose a rendering path

The renderer is selected per report template in Reports → Reports → PDF Renderer. Keep WKHTMLTOPDF as the default unless the alternative backend has been installed and tested on the Odoo host.

2. Base module requirements

• Odoo 19.0 with the standard base and web modules.
• The mg_report_hub directory in an active Odoo add-ons path.
• A writable Odoo filestore for uploaded report images and generated attachment references.
• A working PDF executable for Odoo's standard QWeb report pipeline.
• All fonts used by a report installed or bundled on the Odoo server. A browser font alone is not enough for deterministic PDF output.

3. Renderer A — WKHTMLTOPDF (QWeb)

This is the built-in Report Designer path. The server converts the layout JSON to QWeb-compatible HTML and Odoo passes it to wkhtmltopdf. Report Designer creates a dedicated report action and paper format so physical dimensions, margins and rotation follow the selected template.

Installation checklist

1. Install the wkhtmltopdf build recommended for the deployed Odoo 19 environment.
2. Verify the executable is available to the same operating-system user that runs Odoo.
3. Restart Odoo after changing packages, fonts or executable paths.
4. Upgrade mg_report_hub and rebuild backend assets after deploying a new module version.
5. Print one plain-text report, one image report and one multi-page line-table report.

Important implementation details

• Report actions are configured with UTF-8 encoding to protect umlauts, symbols and currencies.
• Designer images are stored as Odoo attachments; during PDF rendering they are resolved back to safe data-image sources.
• Unsupported raster formats such as WebP or BMP are converted to PNG when possible.
• Fonts are resolved on the server. Missing fonts are silently substituted by wkhtmltopdf, which can change wrapping and pagination.
• Exact paper dimensions may be quantised by wkhtmltopdf. Always verify labels and pre-printed forms with a ruler or production printer.

WKHTMLTOPDF validation

odoo-bin -d <database> -u mg_report_hub

After the update, open a report record, select WKHTMLTOPDF (QWeb), save, choose Print Preview and verify page size, text weight, images, line thickness, header/footer boundaries and final page count.

4. Renderer B — Pango + WeasyPrint

The optional mg_report_render module adds the second renderer. The report still uses the Report Designer layout, but the extension applies Pango-based measurement/wrapping and generates PDF output through WeasyPrint. Cairo is used for drawing and font layout support.

Required system packages

• python3-cairo — Cairo Python bindings.
• python3-gi — PyGObject/GObject introspection.
• gir1.2-pango-1.0 — Pango introspection data.
• python3-gi-cairo — required bridge between PyGObject and Cairo.

Required Python package

• weasyprint — declared by the module manifest as the external Python dependency.

Optional image packages

• python3-cairosvg — improves SVG clipart conversion and rendering.
• python3-pillow — supports JPEG, WebP, BMP and other raster conversions.
• ImageMagick can act as a fallback for problematic WebP images when it is installed on the host.

Example Debian/Ubuntu package installation

sudo apt update
sudo apt install python3-cairo python3-gi gir1.2-pango-1.0 python3-gi-cairo \
  python3-cairosvg python3-pillow ghostscript

# Install WeasyPrint in the same Python environment used by Odoo
python3 -m pip install weasyprint

Environment rule: installing a package into a developer shell is not sufficient when Odoo runs inside a virtual environment, container or managed service. Install it in the interpreter and image used by the Odoo service.

Runtime diagnostics

If Cairo, GI, Pango or the GI-Cairo bridge is missing, the renderer reports the corresponding package name. A bridge error usually means python3-gi-cairo is absent or installed for a different Python interpreter.

python3 -c "import weasyprint; print(weasyprint.__version__)"
python3 -c "import cairo, gi; gi.require_version('Pango','1.0'); gi.require_foreign('cairo'); from gi.repository import Pango, PangoCairo; print('Pango/Cairo OK')"

5. CMYK and Ghostscript

RGB is the safe default. When a template uses CMYK, install ghostscript so the alternative workflow can perform true PDF DeviceCMYK conversion. Without Ghostscript, do not assume that selecting CMYK alone produces press-ready CMYK separations.

• Confirm gs is available to the Odoo service user.
• Inspect the resulting PDF with a preflight tool used by the print provider.
• Validate brand colours on the production output device; screen previews remain RGB displays.
• Keep an RGB master or test copy when switching an established report to CMYK.

6. Deployment procedure

1. Deploy mg_report_hub and, if required, mg_report_render.
2. Install system and Python dependencies on every Odoo application worker image/host.
3. Restart Odoo, update the Apps list and upgrade both modules.
4. Rebuild backend assets and clear stale browser assets if the renderer field or Designer patch is missing.
5. Open Blackfield | Sales Order - Demo, select a renderer and save.
6. Generate output from both Print Preview and the Sales Order Print menu.
7. Compare short, long, empty and multi-line field values; then test multi-page order lines.

7. Acceptance checklist

• Correct physical page size, orientation and margins.
• Installed fonts match the Designer and keep intended bold/italic weights.
• Text wraps within frames and does not enter footer space.
• PNG/JPEG/WebP product images and SVG cliparts render correctly.
• Barcodes scan from the final PDF and a physical print.
• Header/footer repetition and line-table page breaks are correct.
• Restricted-company reports remain hidden and blocked outside their allowed companies.
• CMYK output passes the print provider's PDF preflight when CMYK is required.

8. Troubleshooting

Production recommendation: approve one renderer per report template and keep it stable after sign-off. A renderer switch can change font metrics, wrapping and pagination even when the layout JSON is unchanged.