Plugins natifs Beancount essentiels à connaître
La puissance de Beancount ne réside pas seulement dans son format texte brut, mais aussi 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 imposent les meilleures pratiques comptables. Dans ce guide complet, nous explorerons tous les plugins natifs disponibles dans Beancount et comment les utiliser efficacement.
Que sont les plugins Beancount ?
Les plugins Beancount sont des modules Python qui traitent les écritures de votre grand livre 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 grand livre et peuvent :
- Automatiser les tâches répétitives (ex : création de déclarations de comptes)
- Valider l'intégrité des données (ex : vérification des transactions en double)
- Transformer les écritures (ex : génération d'entrées de prix à partir des transactions)
- Imposer des règles comptables (ex : une seule commodité par compte)
Comment utiliser les plugins
Pour activer un plugin dans votre fichier Beancount, ajoutez une directive plugin en haut de votre grand livre :
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
Certains plugins acceptent des options de configuration :
plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"
Catégories de plugins natifs
Les plugins natifs de Beancount se divisent 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 de tenue de livres répétitives, vous faisant gagner du temps et réduisant les erreurs manuelles.
auto_accounts - Déclarations automatiques de comptes
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 le besoin 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 répétitif (boilerplate).
Exemple :
plugin "beancount.plugins.auto_accounts"
2026-01-01 * "Coffee shop"
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 veulent un grand livre moins verbeux. Cependant, les déclarations de compte explicites peuvent aider à détecter les erreurs de frappe.
close_tree - Fermeture automatique de la hiérarchie des 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
; Ceux-ci 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 lignes d'écriture de transaction qui incluent des coûts (@) ou des prix (@@).
Pourquoi l'utiliser : Alimente votre base de données de prix automatiquement à partir de vos transactions, permettant un reporting précis de la valeur de marché sans saisies manuelles de 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
Ceci génère automatiquement :
2026-01-02 price AAPL 150.00 USD
Quand l'utiliser : Essentiel pour le suivi des investissements et la comptabilité multidevise où vous souhaitez un historique automatique des prix.
2. Plugins de validation
Ces plugins imposent l'intégrité des données et les meilleures pratiques comptables, interceptant les erreurs avant qu'elles ne deviennent des problèmes.
noduplicates - Détection de transactions en double
Ce qu'il fait : Vérifie qu'aucune transaction n'est identique en calculant et en comparant les empreintes (hashes) des données de transaction.
Pourquoi l'utiliser : Prévient les écritures en double accidentelles, particulièrement lors de l'importation de transactions à partir de sources multiples.
Exemple :
plugin "beancount.plugins.noduplicates"
2026-01-02 * "Paiement du loyer"
Expenses:Rent 1200.00 USD
Assets:Checking -1200.00 USD
; Ceci 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 de la déclaration des commodités
Ce qu'il fait : S'assure que toutes les commodités utilisées dans votre grand livre possèdent des directives Commodity correspondantes.
Pourquoi l'utiliser : Impose des déclarations de commodités explicites, vous aidant à maintenir une liste propre d'actifs et de devises.
Exemple :
plugin "beancount.plugins.check_commodity"
2015-01-01 commodity USD
2020-01-01 commodity AAPL
; Ceci déclencherait une erreur sans déclaration de commodité :
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 commodités et éviter les erreurs 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, particulièrement lors de l'utilisation de la comptabilisation au coût moyen.
Pourquoi l'utiliser : Garantit que votre comptabilité analytique reste exacte pour les déclarations fiscales et les calculs de plus-values.
Quand l'utiliser : Crucial pour les portefeuilles d'investissement et tout scénario où le suivi précis des coûts est important.
check_closing - Validation de la clôture du solde
Ce qu'il fait : Développe la métadonnée closing en vérifications de solde, garantissant que les positions sont à zéro après les transactions de clôture.
Pourquoi l'utiliser : Confirme que lorsque vous vendez l'intégralité d'une position, le solde est réellement nul (aucune fraction d'action restante).
Exemple :
plugin "beancount.plugins.check_closing"
2026-01-02 * "Clôture de la position complète AAPL" #closing
Assets:Investments:Stocks -100 AAPL {150.00 USD}
Assets:Cash 15000.00 USD
Income:Investments:Gains -500.00 USD
Le tag #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 s'assurer que rien ne subsiste.
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 le mélange de devises nues (comme 100 USD) avec des devises avec coût (comme 100 USD {1.2 CAD}), ce qui peut provoquer des erreurs comptables.
Quand l'utiliser : Recommandé pour les livres de comptes multi-devises afin de maintenir la cohérence.
leafonly - Application des comptes feuilles
Ce qu'il fait : Garantit que seuls les comptes feuilles (comptes n'ayant pas de sous-comptes enfants) reçoivent des écritures.
Pourquoi l'utiliser : Impose une hiérarchie de comptes propre où les comptes de synthèse comme Expenses:Food n'ont pas d'écritures directes, seuls leurs enfants comme Expenses:Food:Groceries et Expenses:Food:Restaurants en ont.
Exemple :
plugin "beancount.plugins.leafonly"
; Ceci déclencherait une erreur :
2026-01-02 * "Courses alimentaires"
Expenses:Food 50.00 USD ; Erreur : Devrait être imputé à un compte feuille
Assets:Cash -50.00 USD
; Méthode correcte :
2026-01-02 * "Courses alimentaires"
Expenses:Food:Groceries 50.00 USD ; Correct : Écriture sur 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 n'ont jamais été utilisés dans aucune transaction.
Pourquoi l'utiliser : Vous aide à nettoyer vos déclarations de comptes et à identifier d'éventuelles fautes de frappe ou des comptes abandonnés.
Quand l'utiliser : Périodiquement, pour auditer et nettoyer la structure de vos comptes.
onecommodity - Une seule marchandise par compte
Ce qu'il fait : Impose que chaque compte ne détienne qu'un seul type de marchandise.
Pourquoi l'utiliser : Empêche le mélange de différents actifs dans le même compte, ce qui est généralement une meilleure pratique comptable.
Exemple :
plugin "beancount.plugins.onecommodity"
2026-01-02 * "Achat d'actions"
Assets:Investments 10 AAPL @ 150 USD
Assets:Cash -1500.00 USD
; Ceci déclencherait une erreur :
2026-01-03 * "Achat d'autres actions"
Assets:Investments 5 GOOGL @ 140 USD ; Erreur : Marchandise 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 : Compare les plus-values déclarées aux gains calculés à partir des ventes de lots, garantissant que vos calculs de profits/pertes sont exacts.
Pourquoi l'utiliser : Détecte les erreurs dans les calculs manuels de plus-values, ce qui est critique pour une déclaration fiscale précise.
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 ceci est correct
Le plugin vérifiera : Produit de la vente (1500) - Base de coût (1400) = Plus-value (100)
Quand l'utiliser : Indispensable pour toute personne négociant des actions, de la crypto ou d'autres actifs où les plus-values sont importantes.
unique_prices - Vérification de l'unicité des prix
Ce qu'il fait : Garantit qu'il n'y a qu'une seule entrée de prix par marchandise et par date.
Pourquoi l'utiliser : Empêche les données de prix conflictuelles 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.
3. Plugins de transformation
Ces plugins modifient ou enrichissent les données de votre livre de comptes de manières utiles.
currency_accounts - Comptes de conversion de devises
Ce qu'il fait : Implémente des comptes de trading de devises pour suivre explicitement les conversions de change.
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 avez besoin de suivre séparément les gains/pertes de change ou de répondre à des exigences comptables spécifiques.
commodity_attr - Validation des attributs de marchandise
Ce qu'il fait : Valide que les directives de marchandise possèdent les attributs requis (comme export, name, etc.).
Pourquoi l'utiliser : Garantit que les métadonnées de vos marchandises sont complètes et cohérentes.
Quand l'utiliser : Lorsque vous maintenez des métadonnées détaillées sur les marchandises à des fins de reporting ou 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 "souples" ou automatiques en une seule directive.
Quand l'utiliser : Configuration rapide pour les utilisateurs qui souhaitent une automatisation maximale avec une configuration minimale.
pedantic - Tous les plugins de validation
Ce qu'il fait : Active tous les plugins de validation stricte en une seule fois.
Pourquoi l'utiliser : Renforce l'intégrité maximale des données et la rigueur comptable. Idéal pour les grands livres 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 grands livres de production où vous souhaitez 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 offre une automatisation tout en évitant 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 sur Beancount.io
Sur Beancount.io, nous incluons le plugin auto_accounts par défaut dans tous les nouveaux fichiers de grand livre :
plugin "beancount.plugins.auto_accounts"
Cela offre un excellent équilibre entre facilité d'utilisation et fonctionnalités pour commencer rapidement.
Bonnes pratiques
-
Commencez par le minimum, ajoutez au besoin : Commencez avec
auto_accountsetnoduplicates, puis ajoutez des plugins de validation à mesure que votre grand livre évolue. -
Testez les plugins individuellement : Lorsque vous ajoutez plusieurs plugins, activez-les un par un pour comprendre leurs effets.
-
Lisez attentivement les messages d'erreur : Les erreurs de plugin signalent souvent de réels problèmes comptables qui doivent être corrigés.
-
Utilisez
pedanticpour la production : Une fois votre flux de travail établi, envisagez d'activer la validation stricte. -
Combinez avec des plugins personnalisés : Les plugins natifs fonctionnent aux côtés de plugins personnalisés comme le plugin de prévision (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
- Importateurs personnalisés pour les formats CSV spécifiques aux banques
- Calculateurs et rapports spécifiques aux impôts
Explorez l'écosystème Beancount pour plus d'options.
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 de comptabilité 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
- ✅ Se concentrer sur les analyses financières plutôt que sur la saisie de données
Commencez à expérimenter ces plugins dans votre grand livre dès aujourd'hui. Débutez par auto_accounts et implicit_prices, puis ajoutez progressivement des plugins de validation à mesure que vos pratiques comptables évoluent.
Prêt à essayer ces plugins ? Rendez-vous sur Beancount.io et commencez à les utiliser dans votre fichier de grand livre dès aujourd'hui !
Sources
- Référence de l'API des plugins Beancount
- Guide sur les scripts et les 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.
