Odoo 19 : vos PDF reposent encore sur wkhtmltopdf, abandonné

Chaque facture, chaque bon de livraison et chaque devis que votre Odoo 19 transforme en PDF passe par un composant que plus personne ne maintient. Ce composant s'appelle wkhtmltopdf. Il fait le travail depuis des années, discrètement, et beaucoup d'équipes techniques ignorent qu'elles dépendent d'un projet archivé. Le sujet mérite qu'on s'y arrête, parce qu'il touche à la fois la fiabilité de vos rapports et la façon dont vous préparerez vos prochaines migrations.

Comment Odoo fabrique un PDF

Un rapport Odoo est d'abord une vue QWeb, c'est à dire du HTML généré à partir de vos données. Odoo assemble ce HTML, y applique la mise en page (le paperformat, les marges, l'en-tête et le pied de page), puis délègue la conversion en PDF à un binaire externe : wkhtmltopdf ¹. Ce binaire prend le HTML et produit le fichier final. La méthode Python qui orchestre l'opération, _render_qweb_pdf(), reste le point d'entrée que les modules tiers surchargent quand ils veulent changer de moteur.

Cette architecture n'a pas bougé dans Odoo 19. Le rendu HTML a évolué et les vues ont gagné en souplesse, mais l'étape finale repose toujours sur le même outil.

Un moteur figé depuis longtemps

wkhtmltopdf s'appuie sur QtWebKit, un moteur de rendu web dont le développement s'est arrêté il y a plus de dix ans. Qt a retiré QtWebKit de sa distribution à partir de Qt 5.6, en 2016, et le WebKit embarqué dans wkhtmltopdf n'a plus reçu de mise à jour majeure depuis 2012 ². En pratique, le moteur qui rend vos factures ne connaît ni les propriétés CSS récentes, ni les évolutions typographiques des navigateurs actuels.

Le projet lui même a fermé boutique. Le dépôt upstream wkhtmltopdf/wkhtmltopdf a été archivé le 2 janvier 2023 et il est depuis en lecture seule ³. Odoo maintenait sa propre variante dans odoo/wkhtmltopdf ; ce dépôt a lui aussi été archivé, le 29 août 2024, avec un README sans ambiguïté : « This not ready for production use yet, here be dragons! » et « It is not intended for general use » ⁴.

Ce que cela change pour vous, concrètement

Premier point, l'installation. La version packagée dans les dépôts Debian ou Ubuntu ne gère pas les en-têtes et pieds de page, parce qu'elle utilise un Qt non patché. Odoo recommande donc une version précise, 0.12.6.1-3, à récupérer depuis les releases du projet pour Odoo 16 et au delà, Odoo 19 compris ⁵. Si vous voyez des en-têtes qui disparaissent ou des rapports qui sortent vides, cette version est le premier réflexe à vérifier.

Deuxième point, la dette. Un composant abandonné ne reçoit plus de correctif, ni pour les bugs de rendu, ni pour les failles de sécurité éventuelles. Vous héritez donc d'un binaire gelé, dont le comportement ne bougera plus, dans un sens comme dans l'autre. Cela présente un avantage, la stabilité, et un inconvénient, l'absence de recours quand un cas de mise en page résiste.

Troisième point, les limites de rendu. Les problèmes classiques restent d'actualité : du CSS qui fonctionne dans le navigateur mais casse dans le PDF, des sauts de page imprévisibles, des polices qui ne se chargent pas. Ces écarts viennent presque toujours du décalage entre votre navigateur, à jour, et un moteur figé en 2012.

Les alternatives, sans précipitation

Plusieurs équipes contournent wkhtmltopdf en branchant un moteur basé sur Chromium. Gotenberg, par exemple, est une API Docker qui convertit du HTML en PDF via un Chromium sans interface, avec exécution du JavaScript et chargement des polices web ⁶. Côté écosystème Odoo, des modules tiers surchargent _render_qweb_pdf() pour rediriger tout le rendu vers Chrome headless, en conservant vos gabarits QWeb existants.

Ces pistes sont réelles, mais elles ajoutent une brique à opérer : un service supplémentaire à déployer, à surveiller et à sécuriser. Avant de basculer, mesurez ce que vous gagnez. Si vos rapports sortent correctement avec la version recommandée de wkhtmltopdf, passer à un moteur Chromium relève du confort et non de l'urgence. Cette bascule prend son sens lorsque vos gabarits exigent du CSS moderne ou un rendu dynamique que le vieux moteur ne suit plus. Le même raisonnement de coût s'applique d'ailleurs à toute la migration technique d'un parc Odoo 19.

Notre lecture

Le fait marquant tient moins à l'imperfection de l'outil qu'à sa nature : un maillon central de la chaîne documentaire repose sur un projet que ses auteurs ont refermé. Pour une PME, la conséquence pratique est simple. Traitez wkhtmltopdf comme une dépendance à documenter, pas comme un détail d'installation. Notez la version exacte déployée, testez vos rapports critiques à chaque montée de version, et gardez la piste Chromium en réserve pour le jour où un gabarit résistera. Odoo n'a pas annoncé de remplacement officiel, et l'issue ouverte sur le sujet a été refermée sans feuille de route publique ⁷. Ce statu quo va donc durer, et mieux vaut l'organiser que le subir.

Sources

• QWeb Reports, documentation Odoo 19.0 : https://www.odoo.com/documentation/19.0/developer/reference/backend/reports.html
• Dépôt odoo/wkhtmltopdf (archivé) : https://github.com/odoo/wkhtmltopdf
• Dépôt upstream wkhtmltopdf/wkhtmltopdf (archivé) : https://github.com/wkhtmltopdf/wkhtmltopdf
• Wkhtmltopdf, wiki officiel odoo/odoo (versions recommandées) : https://github.com/odoo/odoo/wiki/Wkhtmltopdf
• Issue odoo/odoo #119455, wkhtmltopdf is no longer maintained : https://github.com/odoo/odoo/issues/119455
• Gotenberg, A Docker-based API for PDF conversion : https://gotenberg.dev/
• OCA reporting-engine, Odoo Alternative Reporting Engine : https://github.com/OCA/reporting-engine