Configuration des options

Le comportement de Beancount est personnalisé à l'aide de directives option placées en haut de votre fichier de grand livre principal. Ces paires clé-valeur contrôlent les noms de vos comptes racines, le montant de déséquilibre qu'une transaction peut comporter, et les extensions qui s'exécutent. ⚙️

Chaque option de cette page a été testée avec Beancount 3.2.3, et chaque message d'erreur cité est celui que cette version affiche. Beancount rejette une option qu'il ne reconnaît pas — option "default_tolerance" "USD:0.01" échoue avec Invalid option: 'default_tolerance' — ainsi, une option copiée depuis un guide plus ancien ne peut pas échouer silencieusement. Exécutez bea check sur votre fichier après toute modification ici.

Options de configuration principales​

Ces options contrôlent la configuration fondamentale de votre grand livre.

Paramètres de base​

Ce sont certaines des options les plus courantes que vous définirez.

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"

• title : Définit le titre pour les rapports et les interfaces web. Par défaut : Beancount.
• render_commas : Si vrai, les nombres dans les rapports sont formatés avec des séparateurs de milliers (par exemple, 1,000,000.00). Par défaut : faux. Toute valeur parmi 1, TRUE, true ou yes est lue comme vraie ; toute autre chaîne est lue comme fausse.
• plugin_processing_mode : Soit default (la valeur par défaut), soit raw. Toute autre valeur échoue avec Error for option 'plugin_processing_mode'.

raw n'est pas une version atténuée de default — c'est l'interrupteur qui désactive les étapes de traitement propres à Beancount. Avec default, Beancount exécute beancount.ops.documents avant vos plugins, puis beancount.ops.pad et beancount.ops.balance après ceux-ci. Avec raw, il exécute uniquement les plugins que vous listez vous-même, donc les directives pad ne sont jamais appliquées et les assertions balance ne sont jamais vérifiées :

; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"
 
1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances
 
1970-01-02 * "Opening balance"
  Assets:Cash                100.00 USD
  Equity:Opening-Balances   -100.00 USD
 
1970-01-03 balance Assets:Cash   999.00 USD

Modifiez cette ligne pour la passer à default et le même fichier signalera Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). N'utilisez raw que lorsque vous réimplémentez délibérément ces étapes vous-même.

Personnalisation des noms de comptes​

Vous pouvez renommer les cinq types de comptes fondamentaux de Beancount. Ce n'est pas cosmétique. L'option redéfinit les noms racines que l'analyseur accepte, donc chaque compte de votre fichier doit utiliser le nouveau nom, et l'ancien devient invalide.

option "name_assets" "Actifs"
option "name_expenses" "Depenses"
 
2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation
 
2024-01-02 * "Boulangerie" "Pain"
  Depenses:Alimentation      4.20 EUR
  Actifs:Banque:Courant     -4.20 EUR

Laissez une seule écriture sur l'ancienne racine et le fichier s'arrêtera de charger avec Invalid account name: Assets:Banque:Courant. Les cinq options sont name_assets, name_liabilities, name_equity, name_income et name_expenses ; chaque valeur doit être un mot unique commençant par une majuscule, sans deux-points, sinon vous obtenez l'erreur Error for option 'name_assets': Invalid root account name. Renommez les racines lorsque vous démarrez un grand livre, pas en cours de route.

Configuration des comptes de capitaux propres​

Beancount synthétise plusieurs comptes de capitaux propres lorsqu'il résume une période — soldes d'ouverture, report à nouveau et écarts de conversion. Ces options les désignent.

Chaque valeur est un nom de feuille, et Beancount le joint sous name_equity pour vous. Si vous écrivez la racine vous-même, vous obtenez Equity:Equity:Opening-Balances, ce qui n'est pas le compte que vous vouliez.

option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"

account_rounding est l'exception dans ce groupe : il prend un nom de compte complet et est stocké tel quel, c'est pourquoi Equity:Rounding ci-dessus est correct et non un préfixe dupliqué. Il est également non défini par défaut, et sur Beancount 3.2.3, le définir n'a aucun effet sur le chargement — voir Précision et tolérances pour ce qui se passe réellement avec un résidu.

Paramètres de précision et de tolérance​

Ces options contrôlent le montant de déséquilibre que Beancount accepte dans une transaction.

Configuration de la tolérance par défaut​

Beancount déduit une tolérance pour chaque transaction à partir du nombre de décimales dans ses écritures. Ces trois options ajustent cette déduction.

option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"

• inferred_tolerance_default : Un plancher par devise, utilisé lorsqu'une transaction n'a pas de décimales à partir desquelles déduire. La syntaxe est <currency>:<number>, et * définit toutes les devises à la fois. Répétez l'option pour en définir plusieurs.
• tolerance_multiplier : Le multiplicateur de la plus petite unité significative qui compte comme tolérable, par défaut 0.5. Ce n'est pas une augmentation en pourcentage : 1.2 rend chaque tolérance déduite 2,4 fois la valeur par défaut.
• infer_tolerance_from_cost : Si vrai, les écritures au coût élargissent également la tolérance dans la devise du coût. Désactivé par défaut.

L'ancien nom inferred_tolerance_multiplier définit toujours la même valeur, mais il signale Renamed to 'tolerance_multiplier'. comme une erreur de chargement, donc bea check échoue sur un fichier qui l'utilise. Renommez-le.

Méthode de comptabilisation​

Cette option définit la règle par défaut pour choisir quel lot une réduction prélève. Attribuez une règle différente à un compte individuel via sa directive open.

; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"

Beancount 3.2.3 accepte exactement sept noms : STRICT (la valeur par défaut), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO et AVERAGE. Toute autre valeur est rejetée au chargement avec Error for option 'booking_method' — y compris SIMPLE et FULL, qui ne sont pas des méthodes de comptabilisation et ne l'ont jamais été. AVERAGE est accepté ici mais n'a aucune implémentation derrière lui ; une réduction sous cette méthode lève AVERAGE method is not supported. Gestion des inventaires fonctionne sur les sept méthodes dans le même grand livre.

Gestion des devises​

Une configuration monétaire correcte est essentielle pour des rapports précis.

Devise de fonctionnement​

Une devise de fonctionnement est une devise dans laquelle vous souhaitez que les rapports totalisent. Répétez l'option pour en déclarer plus d'une ; les valeurs s'accumulent plutôt que de se remplacer.

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

Déclarer des devises de fonctionnement indique aux outils de rapport de donner à chacune sa propre colonne. conversion_currency nomme la devise imaginaire dans laquelle Beancount comptabilise les conversions à un taux de zéro ; elle est déjà définie par défaut à NOTHING, et la seule raison de la définir est de choisir un autre espace réservé que votre grand livre n'utilise définitivement jamais comme une marchandise réelle.

Gestion des documents​

Beancount peut lier des transactions à des fichiers externes comme des reçus ou des factures. L'option documents lui donne un dossier à analyser.

option "documents" "/home/user/Documents/beancount"

Le chemin dans ce bloc est une illustration — remplacez-le par le vôtre avant de l'exécuter. Les règles sont strictes, et chacune d'elles est un no-op silencieux plutôt qu'une erreur lorsque vous vous trompez :

• Le dossier doit exister. Un dossier manquant fait échouer le chargement avec Document root '/no/such/place' does not exist.
• Les sous-dossiers sont des noms de comptes. Un relevé pour Assets:US:BofA:Checking appartient à <root>/Assets/US/BofA/Checking/. Un fichier posé librement à la racine est ignoré.
• Le compte doit être ouvert. Les documents trouvés sous un compte que votre grand livre n'ouvre jamais sont ignorés sans avertissement.
• Les noms de fichiers commencent par une date, sous la forme YYYY-MM-DD.description.ext (par exemple, 2025-07-28.amazon-order.pdf). Tout le reste dans le dossier est ignoré.
• Les chemins peuvent être absolus ou relatifs au fichier de grand livre principal, et l'option peut être répétée pour plusieurs dossiers.

Système de plugins​

Les fonctionnalités de Beancount peuvent être étendues avec des plugins.

Configuration des plugins​

Un plugin est chargé avec une directive plugin autonome, pas avec option. option "plugin" "..." échoue avec Option 'plugin' may not be set.

plugin "beancount.plugins.auto_accounts"
 
2024-03-01 * "Coffee Shop" "Flat white"
  Expenses:Food:Coffee        4.50 USD
  Assets:US:BofA:Checking    -4.50 USD

Ce fichier se charge parce que auto_accounts ouvre les deux comptes pour vous ; supprimez la ligne plugin et il signalera Invalid reference to unknown account 'Expenses:Food:Coffee'. Un plugin qui prend une configuration la reçoit comme deuxième chaîne, plugin "module" "config". Les plugins s'exécutent dans l'ordre où vous les écrivez, après l'étape documents de Beancount et avant ses étapes pad et balance — à moins que vous ne définissiez plugin_processing_mode sur raw, ce qui supprime complètement ces étapes.

Limites techniques et contraintes​

Ces options contrôlent les aspects techniques de l'analyseur Beancount.

Gestion des chaînes​

Vous pouvez définir une limite sur le nombre de lignes autorisées dans une chaîne multiligne, afin qu'une citation non terminée soit signalée près de l'endroit où vous l'avez tapée plutôt qu'à la fin du fichier.

option "long_string_maxlines" "64"

Précision d'interpolation​

Par défaut, Beancount utilise une seule tolérance pour deux tâches différentes : combler un montant manquant et décider si la transaction est équilibrée. Activer cette option utilise la tolérance déduite la plus fine pour la première et la plus lâche pour la seconde, ce qui empêche les montants interpolés de dériver.

option "use_precise_interpolation" "TRUE"

Il n'y a pas d'option pour des tolérances explicites sur une écriture. La seule syntaxe de tolérance explicite que Beancount 3.2.3 possède est le tilde sur une directive balance — 4.271 ~ 0.01 RGAGX — et elle n'a besoin d'aucune option. Un tilde à l'intérieur d'une écriture de transaction est une erreur de syntaxe.

Options obsolètes et supprimées​

Trois options que les guides plus anciens recommandent encore n'existent pas dans Beancount 3.2.3. Chaque ligne de ce bloc fait échouer le chargement :

option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"

• experiment_explicit_tolerances — la syntaxe ~ au niveau des écritures qu'elle activait a disparu ; utilisez le tilde d'une directive balance à la place.
• use_legacy_fixed_tolerances — les tolérances fixes 0.005/0.015 ont disparu ; la tolérance est déduite par transaction, ajustée avec tolerance_multiplier et inferred_tolerance_default.
• default_tolerance — remplacée par inferred_tolerance_default pour l'équilibrage et display_precision pour le rendu.

Trois autres fonctionnent encore mais signalent une erreur d'obsolescence, ce qui suffit à faire échouer bea check :

• inferred_tolerance_multiplier — renommée en tolerance_multiplier.
• allow_pipe_separator — accepte l'ancien | entre le bénéficiaire et la narration.
• allow_deprecated_none_for_tags_and_links — accepte un None littéral là où les balises et les liens doivent se trouver.

Les options de Fava sont distinctes​

Tout ce qui figure sur cette page est lu par Beancount lui-même. Les paramètres propres à Fava ne sont pas du tout des directives option — ce sont des directives custom "fava-option" avec une date, et Beancount les ignore. Écrire un paramètre Fava comme une option échoue avec Invalid option. Voir Options Fava pour cette liste.

Configuration recommandée ✅​

Pour la plupart des utilisateurs, la configuration suivante constitue un point de départ robuste et sensé. C'est un seul fichier, et il se charge.

; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
 
; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"
 
; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"
 
; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"

Les commentaires commencent par ;. Un commentaire // est une erreur de syntaxe dans Beancount, et il entraîne le reste du fichier avec lui.

Cette configuration fournit une base solide pour un nouveau grand livre Beancount, garantissant des rapports clairs, un contrôle de précision raisonnable et une structure de comptes de capitaux propres logique.