Beancount v3 : Quoi de neuf ?

À jour au 15/09/2026.

La version 3 de Beancount, publiée à la mi-2024, marque une évolution architecturale significative pour l'outil populaire de comptabilité en texte brut. Bien qu'elle conserve la rétrocompatibilité des fichiers de grand livre des utilisateurs, la structure sous-jacente et les outils qui l'accompagnent ont subi des changements substantiels. Voici un aperçu des nouveautés de Beancount v3 — et de ce qui est arrivé dans la série 3.1–3.2 depuis la première publication de ce guide.

Pour la syntaxe et les premiers grands livres, voir la référence de syntaxe Beancount et Commencer. Pour le CLI hébergé qui englobe la vérification, les requêtes, l'importation et les rapports, voir la référence du CLI Beancount.

Une architecture plus modulaire et rationalisée​

Le changement le plus important de Beancount v3 est le passage à un écosystème plus modulaire. Plusieurs fonctionnalités clés auparavant regroupées avec le cœur ont été scindées en projets indépendants distincts. Cela rend le cœur de Beancount plus léger et permet un développement plus ciblé sur les composants individuels.

Les composants clés désormais séparés en packages incluent :

• beanquery : l'outil de requête de type SQL pour vos fichiers de grand livre est désormais dans son propre package.
• beangulp : c'est le nouveau foyer du framework d'importation de données, remplaçant l'ancien module beancount.ingest.
• beanprice : un outil dédié à la récupération des prix des matières premières et des actions.

Cette séparation implique que les utilisateurs devront installer ces packages en plus de beancount lui-même pour conserver toutes les fonctionnalités auxquelles ils étaient habitués dans la version 2.

Changements dans les outils en ligne de commande et les flux de travail​

Reflétant la nouvelle architecture modulaire, il y a quelques changements notables dans les outils en ligne de commande :

• bean-report a disparu : cet outil a été supprimé. Les utilisateurs sont désormais encouragés à utiliser bean-query (du package beanquery) pour leurs besoins de rapport.
• Nouveau flux de travail pour les importateurs : les commandes bean-extract et bean-identify ont été retirées du cœur. La nouvelle approche avec beangulp est basée sur des scripts. Les utilisateurs créeront désormais leurs propres scripts Python pour gérer l'importation de données à partir de sources externes comme les relevés bancaires.

Améliorations de la syntaxe et des fonctionnalités​

Bien que les principes comptables de base restent les mêmes, Beancount v3 introduit une flexibilité bienvenue dans sa syntaxe :

• Codes de devise plus flexibles : les restrictions précédentes sur la longueur et les caractères des noms de devises ont été assouplies. Les symboles de devise à un caractère sont désormais pris en charge.
• Drapeaux de transaction élargis : les utilisateurs peuvent désormais utiliser n'importe quelle lettre majuscule de A à Z comme drapeau pour les transactions, permettant une catégorisation plus granulaire.

Important : ces changements sont rétrocompatibles, donc vos fichiers de grand livre Beancount v2 existants fonctionneront sans aucune modification.

La réécriture en C++ et les performances​

L'un des objectifs à long terme pour Beancount a été une réécriture de ses composants critiques pour les performances en C++. La version initiale de Beancount v3 n'incluait pas de cœur C++, et au 15/09/2026 cela reste vrai : la ligne PyPI publiée (jusqu'à 3.2.3) est toujours la branche v3 Python modulaire. Le travail historique C++/Bazel vit sur une branche distincte cpp et ne fait pas partie des packages que les utilisateurs installent depuis PyPI. Les performances quotidiennes des versions v3 actuelles sont donc de la même classe que la fin de la v2, avec des améliorations incrémentales du parseur et des outils plutôt qu'une réécriture C++ d'un ordre de grandeur.

Depuis la rédaction de ce guide (v3.1 → v3.2.x)​

Sources principales : le fichier CHANGES du projet, les vues de comparaison GitHub pour 3.1.0...3.2.0, et PyPI beancount (dernière 3.2.3 au 15/09/2026).

• Série 3.1.x — Nettoyage continu du packaging et de l'API après la scission modulaire 3.0 (beanquery, beangulp, beanprice restent des installations séparées).
• 3.2.0 (14/09/2025) — Commit de version sur beancount/beancount ; le travail notable orienté utilisateur dans cette fenêtre inclut bean-format multi-fichiers, des raffinements de tolérance/précision, et la maintenance des wheels/CI (voir le lien de comparaison ci-dessus).
• 3.2.1–3.2.3 (2026) — Versions binaires et de packaging de suivi (y compris la couverture de tests Python 3.14 et l'échafaudage de documentation mentionnés dans le résumé 3.2.1 sur la liste de diffusion). Installez avec pip install -U beancount et épinglez les compagnons (beanquery, beangulp) aux majeurs correspondants lors de la mise à niveau.

Fava : Fava 1.30 a ajouté la prise en charge de Beancount 3 (29/12/2024). Fava 1.30.13 (19/05/2026) a abandonné la prise en charge de Beancount 2 et attend beangulp pour les importateurs. La ligne PyPI actuelle au 15/09/2026 est 1.30.16. Associez les mises à jour de Fava à un grand livre Beancount 3.

Migration de v2 vers v3​

Pour la plupart des utilisateurs, la migration de Beancount v2 vers v3 est relativement simple :

1. Fichiers de grand livre : aucune modification n'est nécessaire pour vos fichiers .beancount.
2. Installation : vous devrez installer les nouveaux packages séparés comme beanquery et beangulp avec pip.
3. Scripts d'importateur : si vous avez des importateurs personnalisés, vous devrez les mettre à jour pour utiliser la nouvelle API beangulp. Cela implique principalement de changer la classe de base dont vos importateurs héritent et d'ajuster certaines signatures de méthodes.
4. Fava : l'interface web populaire pour Beancount, Fava, a été mise à jour pour être compatible avec la v3. Assurez-vous d'avoir la dernière version de Fava pour une expérience fluide.

En substance, Beancount v3 est une version fondatrice qui rationalise l'architecture du projet, la rendant plus modulaire et plus facile à maintenir et à étendre à long terme. Bien qu'elle exige quelques ajustements dans les flux de travail des utilisateurs, en particulier autour de l'importation de données, elle prépare le terrain pour le développement futur de cet outil de comptabilité puissant.

Pour aller plus loin​

• Commencer avec Beancount
• Référence de syntaxe Beancount
• Référence du CLI Beancount (bea)
• Configurations communautaires, plugins et flux de travail