Les plugins natifs essentiels de Beancount que vous devriez connaître

À jour au 2026-09-15.

La puissance de Beancount ne réside pas seulement dans son format en texte brut, mais dans son extensibilité grâce aux plugins. Les plugins natifs sont des modules intégrés qui améliorent les fonctionnalités de Beancount, automatisent les tâches fastidieuses et appliquent les meilleures pratiques comptables. Dans ce guide complet, nous explorerons tous les plugins natifs disponibles dans Beancount et comment les utiliser efficacement.

Pour la syntaxe des directives sur lesquelles ces plugins opèrent, consultez la référence de syntaxe Beancount. Pour les flux de travail communautaires réels qui combinent des plugins avec des importateurs et Fava, consultez la vitrine communautaire. Les options du registre qui interagissent avec les plugins se trouvent dans la configuration des options.

Que sont les plugins Beancount ?​

Les plugins Beancount sont des modules Python qui traitent les entrées de votre registre pour ajouter des capacités d'automatisation, de validation ou de transformation. Ils s'exécutent pendant la phase de chargement de votre fichier de registre et peuvent :

• Automatiser les tâches répétitives (par exemple, créer des déclarations de comptes)
• Valider l'intégrité des données (par exemple, vérifier les transactions en double)
• Transformer les entrées (par exemple, générer des entrées de prix à partir de transactions)
• Appliquer les règles comptables (par exemple, une devise par compte)

Comment utiliser les plugins​

Pour activer un plugin dans votre fichier Beancount, ajoutez une directive plugin en haut de votre registre :

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

Certains plugins acceptent des options de configuration :

; @m49-fragment dateless
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"

Catégories de plugins natifs​

Les plugins natifs de Beancount se répartissent en quatre catégories principales :

1. Plugins d'automatisation​

2. Plugins de validation​

3. Plugins de transformation​

4. Méta-plugins​

1. Plugins d'automatisation​

Ces plugins automatisent les tâches comptables répétitives, vous faisant gagner du temps et réduisant les erreurs manuelles.

auto_accounts - Déclarations de comptes automatiques​

Ce qu'il fait : Insère automatiquement des directives Open pour les comptes qui apparaissent dans les transactions mais n'ont pas été explicitement déclarés.

Pourquoi l'utiliser : Élimine la nécessité de déclarer manuellement chaque compte avant de l'utiliser. Parfait pour démarrer rapidement ou pour les utilisateurs qui préfèrent un minimum de code passe-partout.

Exemple :

plugin "beancount.plugins.auto_accounts"
 
2026-01-01 * "Café"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Sans le plugin, vous devriez ajouter manuellement :

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

Quand l'utiliser : Idéal pour les débutants ou ceux qui souhaitent un registre moins verbeux. Cependant, les déclarations de comptes explicites peuvent aider à détecter les fautes de frappe.

close_tree - Fermeture automatique de la hiérarchie de comptes​

Ce qu'il fait : Lorsque vous fermez un compte parent, ce plugin ferme automatiquement tous ses comptes descendants.

Pourquoi l'utiliser : Maintient la cohérence dans votre hiérarchie de comptes. Si vous fermez Assets:Investments, tous les sous-comptes comme Assets:Investments:Stocks et Assets:Investments:Bonds seront fermés automatiquement.

Exemple :

plugin "beancount.plugins.close_tree"
 
2025-06-30 close Assets:Investments
 
; Ces comptes seront automatiquement fermés :
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

Quand l'utiliser : Lors de la restructuration de votre hiérarchie de comptes ou de la fermeture de catégories entières de comptes.

implicit_prices - Génération automatique d'entrées de prix​

Ce qu'il fait : Synthétise des directives Price à partir des écritures de transactions qui incluent des coûts (@) ou des prix (@@).

Pourquoi l'utiliser : Remplit automatiquement votre base de données de prix à partir de vos transactions, permettant un rapport de valeur de marché précis sans saisie manuelle des prix.

Exemple :

plugin "beancount.plugins.implicit_prices"
 
2026-01-02 * "Achat d'actions AAPL"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

Cela génère automatiquement :

2026-01-02 price AAPL  150.00 USD

Quand l'utiliser : Essentiel pour le suivi des investissements et la comptabilité multi-devises lorsque vous souhaitez un historique des prix automatique.

2. Plugins de validation​

Ces plugins appliquent l'intégrité des données et les meilleures pratiques comptables, détectant les erreurs avant qu'elles ne deviennent des problèmes.

noduplicates - Détection des transactions en double​

Ce qu'il fait : Vérifie qu'aucune transaction n'est identique en calculant et en comparant des hachages des données de transaction.

Pourquoi l'utiliser : Empêche les entrées en double accidentelles, en particulier lors de l'importation de transactions provenant de plusieurs sources.

Exemple :

; @m49-fragment expected-failure
plugin "beancount.plugins.noduplicates"
 
2026-01-02 * "Paiement du loyer"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD
 
; Cela déclencherait une erreur :
2026-01-02 * "Paiement du loyer"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

Quand l'utiliser : Toujours recommandé, surtout si vous importez des relevés bancaires ou utilisez plusieurs sources de données.

check_commodity - Validation des déclarations de devises​

Ce qu'il fait : S'assure que toutes les devises utilisées dans votre registre ont des directives Commodity correspondantes.

Pourquoi l'utiliser : Applique des déclarations de devises explicites, vous aidant à maintenir une liste propre des actifs et des devises.

Exemple :

; @m49-fragment expected-failure
plugin "beancount.plugins.check_commodity"
 
2015-01-01 commodity USD
2020-01-01 commodity AAPL
 
; Cela déclencherait une erreur sans déclaration de devise :
2026-01-02 * "Achat de Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

Quand l'utiliser : Recommandé pour maintenir un suivi strict des devises et éviter les fautes de frappe dans les symboles boursiers.

check_average_cost - Validation de la base de coût​

Ce qu'il fait : Vérifie que la base de coût est correctement préservée dans les transactions, en particulier lors de l'utilisation de la comptabilité au coût moyen.

Pourquoi l'utiliser : Garantit que votre comptabilité des coûts reste précise pour les déclarations fiscales et les calculs de plus-values.

Quand l'utiliser : Critique pour les portefeuilles d'investissement et tout scénario où un suivi précis des coûts est important.

check_closing - Validation de la clôture des soldes​

Ce qu'il fait : Étend les métadonnées closing en vérifications de solde, garantissant que les positions sont à zéro après les opérations de clôture.

Pourquoi l'utiliser : Confirme que lorsque vous vendez une position entière, le solde est vraiment à zéro (aucune fraction d'action restante).

Exemple :

plugin "beancount.plugins.check_closing"
 
2026-01-02 * "Clôture de la position AAPL entière" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15500.00 USD
  Income:Investments:Gains    -500.00 USD

La balise #closing indique au plugin de vérifier que votre position AAPL est à zéro après cette transaction.

Quand l'utiliser : Lors de la vente de positions entières pour garantir qu'aucun solde ne reste.

coherent_cost - Vérification de la cohérence devise/coût​

Ce qu'il fait : Valide que les devises ne sont pas utilisées de manière incohérente — à la fois avec et sans annotations de coût.

Pourquoi l'utiliser : Empêche de mélanger les devises nues (comme 100 USD) avec des devises à coût (comme 100 USD {1.2 CAD}), ce qui peut provoquer des erreurs comptables.

Quand l'utiliser : Recommandé pour les registres multi-devises afin de maintenir la cohérence.

leafonly - Application des comptes feuilles​

Ce qu'il fait : S'assure que seuls les comptes feuilles (comptes sans enfants) reçoivent des écritures.

Pourquoi l'utiliser : Applique une hiérarchie de comptes propre où les comptes de synthèse comme Expenses:Food n'ont pas d'écritures directes, seulement leurs enfants comme Expenses:Food:Groceries et Expenses:Food:Restaurants.

Exemple :

; @m49-fragment expected-failure
plugin "beancount.plugins.leafonly"
 
; Cela déclencherait une erreur :
2026-01-02 * "Achats alimentaires"
  Expenses:Food              50.00 USD  ; Erreur : doit écrire dans un compte feuille
  Assets:Cash               -50.00 USD
 
; Manière correcte :
2026-01-02 * "Achats alimentaires"
  Expenses:Food:Groceries    50.00 USD  ; Correct : écriture dans un compte feuille
  Assets:Cash               -50.00 USD

Quand l'utiliser : Lorsque vous souhaitez maintenir une comptabilité hiérarchique stricte avec une catégorisation claire.

nounused - Détection des comptes inutilisés​

Ce qu'il fait : Identifie les comptes qui ont été ouverts mais jamais réellement utilisés dans des transactions.

Pourquoi l'utiliser : Aide à nettoyer vos déclarations de comptes et à identifier les fautes de frappe potentielles ou les comptes abandonnés.

Quand l'utiliser : Périodiquement, pour auditer et nettoyer votre structure de comptes.

onecommodity - Une seule devise par compte​

Ce qu'il fait : Applique que chaque compte ne détienne qu'un seul type de devise.

Pourquoi l'utiliser : Empêche de mélanger différents actifs dans le même compte, ce qui est généralement une bonne pratique comptable.

Exemple :

; @m49-fragment expected-failure
plugin "beancount.plugins.onecommodity"
 
2026-01-02 * "Achat d'actions"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD
 
; Cela déclencherait une erreur :
2026-01-03 * "Achat de plus d'actions"
  Assets:Investments         5 GOOGL @ 140 USD  ; Erreur : devise différente
  Assets:Cash              -700.00 USD

Quand l'utiliser : Lorsque vous préférez une séparation stricte des comptes (un compte par action/actif).

sellgains - Validation des plus-values​

Ce qu'il fait : Recoupe les plus-values déclarées avec les gains calculés à partir des ventes de lots, garantissant que vos calculs de profits/pertes sont précis.

Pourquoi l'utiliser : Détecte les erreurs dans les calculs manuels de plus-values, essentiel pour des déclarations fiscales précises.

Exemple :

plugin "beancount.plugins.sellgains"
 
2026-01-02 * "Vente d'actions AAPL"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Le plugin valide que c'est correct

Le plugin vérifiera : Produit de la vente (1500) - Base de coût (1400) = Gains (100)

Quand l'utiliser : Essentiel pour toute personne négociant des actions, des cryptomonnaies ou d'autres actifs où les plus-values comptent.

unique_prices - Vérification de l'unicité des prix​

Ce qu'il fait : S'assure qu'il n'y a qu'une seule entrée de prix par devise et par date.

Pourquoi l'utiliser : Empêche les données de prix contradictoires qui pourraient conduire à des évaluations incorrectes.

Quand l'utiliser : Recommandé lors de la saisie manuelle des prix ou de l'importation depuis plusieurs sources de prix.

check_drained - Validation des comptes vidés​

Ce qu'il fait : Signale les comptes qui conservent encore un solde (y compris les devises sans prix ou les lots restants) lorsque vous attendiez qu'ils soient vides après des transferts ou des clôtures.

Pourquoi l'utiliser : Détecte les soldes résiduels que les assertions balance et les balises #closing peuvent manquer — particulièrement utile après des mouvements multi-devises.

Statut (vérifié le 2026-09-15) : Présent dans l'arborescence Beancount 3.x à beancount/plugins/check_drained.py sur la ligne PyPI actuelle (3.2.3).

Quand l'utiliser : Après de grandes réorganisations de portefeuille ou lors de la fermeture de comptes de courtier.

3. Plugins de transformation​

Ces plugins modifient ou améliorent les données de votre registre de manière utile.

currency_accounts - Comptes de négociation de devises​

Ce qu'il fait : Implémente des comptes de négociation de devises pour suivre explicitement les conversions forex.

Pourquoi l'utiliser : Fournit un suivi détaillé des transactions de conversion de devises, utile pour les normes comptables qui l'exigent.

Quand l'utiliser : Lorsque vous devez suivre les gains/pertes forex séparément ou répondre à des exigences comptables spécifiques.

commodity_attr - Validation des attributs de devises​

Ce qu'il fait : Valide que les directives de devises ont les attributs requis (comme export, name, etc.).

Pourquoi l'utiliser : Garantit que vos métadonnées de devises sont complètes et cohérentes.

Quand l'utiliser : Lorsque vous maintenez des métadonnées de devises détaillées pour des rapports ou des besoins d'exportation.

4. Méta-plugins​

Ces plugins sont des collections d'autres plugins pour plus de commodité.

auto - Tous les plugins automatiques​

Ce qu'il fait : Active une collection de plugins "laxistes" ou automatiques en une seule directive.

Quand l'utiliser : Configuration rapide pour les utilisateurs qui veulent une automatisation maximale avec une configuration minimale.

pedantic - Tous les plugins de validation​

Ce qu'il fait : Active tous les plugins de validation stricts en même temps.

Pourquoi l'utiliser : Applique une intégrité maximale des données et une rigueur comptable. Parfait pour les registres de production ou lorsque la précision est primordiale.

Exemple :

plugin "beancount.plugins.pedantic"
 
; Cela équivaut à activer :
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

Quand l'utiliser : Pour les registres de production où vous voulez une validation maximale et êtes prêt à maintenir des pratiques comptables plus strictes.

Configurations de plugins recommandées​

Pour les débutants​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"

Cet ensemble minimal fournit l'automatisation tout en prévenant les erreurs courantes.

Pour les investisseurs​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"

Se concentre sur le suivi des investissements et la précision des plus-values.

Pour une comptabilité stricte​

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

Validation maximale pour les environnements de production.

Configuration par défaut chez Beancount.io​

Chez Beancount.io, nous incluons le plugin auto_accounts par défaut dans tous les nouveaux fichiers de registre :

plugin "beancount.plugins.auto_accounts"

Cela offre un excellent équilibre entre facilité d'utilisation et fonctionnalité pour démarrer rapidement.

Statut des plugins vérifié le 2026-09-15​

Par rapport à l'arborescence beancount/plugins en direct sur Beancount 3.2.3 (PyPI, 2026-09-15) :

Rien dans cet ensemble natif n'a été supprimé entre le brouillon original de ce guide et la date ci-dessus. Les plugins communautaires (non natifs) appartiennent toujours à la liste Awesome Beancount plugins et à la vitrine communautaire — traitez les dépôts tiers comme étant versionnés indépendamment et vérifiez la dernière version de chaque dépôt avant de les activer sur un registre de production.

Meilleures pratiques​

1. Commencez minimal, ajoutez selon les besoins : Commencez avec auto_accounts et noduplicates, puis ajoutez des plugins de validation à mesure que votre registre mûrit.

2. Testez les plugins individuellement : Lors de l'ajout de plusieurs plugins, activez-les un par un pour comprendre leurs effets.

3. Lisez attentivement les messages d'erreur : Les erreurs de plugins pointent souvent vers de véritables problèmes comptables à corriger.

4. Utilisez pedantic pour la production : Une fois votre flux de travail établi, envisagez d'activer la validation stricte.

5. Combinez avec des plugins personnalisés : Les plugins natifs fonctionnent aux côtés de plugins personnalisés comme le plugin forecast pour une fonctionnalité maximale.

Au-delà des plugins natifs​

Bien que les plugins natifs fournissent les fonctionnalités de base, l'écosystème Beancount comprend de nombreux plugins développés par la communauté pour des besoins spécialisés :

• fava.plugins.forecast - Pour la prévision des transactions récurrentes
• fava.plugins.link_documents - Pour lier les transactions aux fichiers de reçus
• Des importateurs personnalisés pour les formats CSV spécifiques aux banques
• Calculateurs et rapports fiscaux spécifiques

Explorez l'écosystème Beancount pour plus d'options, et la vitrine communautaire pour voir comment les gens combinent les plugins natifs avec des importateurs et Fava.

Conclusion​

Les plugins natifs de Beancount transforment la comptabilité en texte brut d'un processus manuel en un système de gestion financière automatisé, validé et robuste. En comprenant et en exploitant ces outils intégrés, vous pouvez :

• ✅ Automatiser les tâches comptables fastidieuses
• ✅ Détecter les erreurs avant qu'elles ne deviennent des problèmes
• ✅ Maintenir une intégrité stricte des données
• ✅ Générer des rapports financiers précis
• ✅ Vous concentrer sur les informations financières plutôt que sur la saisie de données

Commencez à expérimenter avec ces plugins dans votre registre dès aujourd'hui. Commencez avec auto_accounts et implicit_prices, puis ajoutez progressivement des plugins de validation à mesure que vos pratiques comptables mûrissent.

Prêt à essayer ces plugins ? Rendez-vous sur Beancount.io et commencez à les utiliser dans votre fichier de registre dès aujourd'hui !

Sources​

• Référence API des plugins Beancount
• Guide de script et plugins Beancount
• Plugins et options Beancount par Bryan Alves
• Dépôt GitHub Beancount

Vous avez des questions sur les plugins Beancount ? Rejoignez la discussion sur notre forum communautaire ou consultez notre documentation.

Explorez un exemple de registre de cryptomonnaies en direct :