Configurare i ledger Beancount con le direttive option

Il comportamento di Beancount viene personalizzato con direttive option poste all'inizio di il tuo file di registro principale. Queste coppie chiave-valore controllano i nomi dei tuoi conti radice, quanto sbilanciamento una transazione può contenere e quali estensioni vengono eseguite. ⚙️

Ogni opzione in questa pagina è stata caricata con Beancount 3.2.3, e ogni messaggio di errore citato è quello stampato da questa versione. Beancount rifiuta un'opzione che non riconosce — option "default_tolerance" "USD:0.01" fallisce con Invalid option: 'default_tolerance' — quindi un'opzione copiata da una guida più vecchia non fallisce in silenzio. Esegui bea check sul tuo file dopo aver modificato qualsiasi cosa qui.

Opzioni di Configurazione Principali​

Queste opzioni controllano l'impostazione fondamentale del tuo registro.

Impostazioni di Base​

Queste sono alcune delle opzioni più comuni che imposterai.

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

• title: Imposta il titolo per report e interfacce web. Il valore predefinito è Beancount.
• render_commas: Se true, i numeri nei report sono formattati con separatori delle migliaia (es., 1,000,000.00). Il valore predefinito è false. Qualsiasi valore tra 1, TRUE, true o yes viene letto come true; qualsiasi altra stringa viene letta come false.
• plugin_processing_mode: O default (il valore predefinito) oppure raw. Qualsiasi altro valore fallisce con Error for option 'plugin_processing_mode'.

raw non è una versione più leggera di default — è l'interruttore che disattiva le fasi di elaborazione di Beancount stesso. Con default, Beancount esegue beancount.ops.documents prima dei tuoi plugin e beancount.ops.pad e beancount.ops.balance dopo di essi. Con raw esegue solo i plugin che elenchi tu stesso, quindi le direttive pad non vengono mai applicate e le verifiche balance non vengono mai eseguite:

; 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

Cambia quella riga in default e lo stesso file riporta Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Usa raw solo quando stai deliberatamente reimplementando quelle fasi da solo.

Personalizzazione dei Nomi dei Conti​

Puoi rinominare i cinque tipi di conto fondamentali di Beancount. Questa non è un'operazione estetica. L'opzione ridefinisce quali nomi radice il parser accetta, quindi ogni conto nel tuo file deve usare il nuovo nome e il vecchio diventa non valido.

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

Lascia una singola registrazione sulla vecchia radice e il file smette di caricarsi con Invalid account name: Assets:Banque:Courant. Le cinque opzioni sono name_assets, name_liabilities, name_equity, name_income e name_expenses; ogni valore deve essere una singola parola con la maiuscola senza due punti, altrimenti ottieni Error for option 'name_assets': Invalid root account name. Rinomina le radici quando inizi un registro, non a metà.

Configurazione dei Conti di Patrimonio Netto​

Beancount sintetizza diversi conti di patrimonio netto quando riepiloga un periodo — saldi di apertura, utili portati a nuovo e conversioni di valuta. Queste opzioni li nominano.

Ogni valore è un nome di foglia e Beancount lo unisce sotto name_equity per te. Scrivere la radice del patrimonio netto da soli produce Equity:Equity:Opening-Balances, che è un conto diverso da quello che intendevi.

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 è l'eccezione in questo gruppo: accetta un nome completo del conto e viene memorizzato esattamente come scritto, motivo per cui Equity:Rounding sopra è corretto e non un prefisso raddoppiato. Inoltre, non è impostato per impostazione predefinita e su Beancount 3.2.3 impostarlo non ha alcun effetto sul caricamento — consulta Precisione e Tolleranze per ciò che accade realmente a un residuo.

Impostazioni di Precisione e Tolleranza​

Queste opzioni controllano quanto sbilanciamento Beancount accetta in una transazione.

Configurazione della Tolleranza Predefinita​

Beancount deduce una tolleranza per ogni transazione dal numero di cifre decimali nelle sue registrazioni. Queste tre opzioni regolano quella deduzione.

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

• inferred_tolerance_default: Un livello minimo per valuta, usato quando una transazione non ha decimali da cui dedurre. La sintassi è <currency>:<number> e * imposta tutte le valute contemporaneamente. Ripeti l'opzione per impostarne diverse.
• tolerance_multiplier: La frazione della cifra più piccola che conta come tollerabile, predefinito 0.5. Non è un aumento percentuale: 1.2 rende ogni tolleranza dedotta 2.4 volte quella predefinita.
• infer_tolerance_from_cost: Se true, le registrazioni mantenute al costo ampliano la tolleranza anche nella valuta di costo. Disattivata per impostazione predefinita.

Il vecchio nome inferred_tolerance_multiplier imposta ancora lo stesso valore, ma riporta Renamed to 'tolerance_multiplier'. come errore di caricamento, quindi bea check fallisce su un file che lo usa. Rinominalo.

Metodo di Prenotazione​

Questa opzione imposta la regola predefinita per scegliere quale lotto viene prelevato da una riduzione. Dai a un conto una regola diversa sulla sua direttiva open.

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

Beancount 3.2.3 accetta esattamente sette nomi: STRICT (il predefinito), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO e AVERAGE. Qualsiasi altro valore viene rifiutato al caricamento con Error for option 'booking_method' — incluso SIMPLE e FULL, che non sono metodi di prenotazione e non lo sono mai stati. AVERAGE è accettato qui ma non ha alcuna implementazione dietro; una riduzione sotto di esso solleva AVERAGE method is not supported. Gestione dell'Inventario funziona con tutti e sette sullo stesso registro.

Gestione delle Valute​

Una corretta configurazione delle valute è fondamentale per una reportistica accurata.

Valuta Operativa​

Una valuta operativa è una valuta in cui desideri che i report totalizzino. Ripeti l'opzione per dichiararne più di una; i valori si accumulano piuttosto che sostituirsi a vicenda.

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

La dichiarazione delle valute operative dice agli strumenti di reportistica di dare a ciascuna la propria colonna. conversion_currency nomina la valuta immaginaria in cui Beancount registra le conversioni a un tasso di zero; è già predefinita a NOTHING, e l'unico motivo per impostarla è scegliere un segnaposto diverso che il tuo registro sicuramente non usa mai come merce reale.

Gestione dei Documenti​

Beancount può collegare le transazioni a file esterni come ricevute o fatture. L'opzione documents gli fornisce una cartella da scansionare.

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

Il percorso in quel blocco è un'illustrazione — sostituisci il tuo prima di eseguirlo. Le regole sono rigide e ciascuna di esse è una non-operazione silenziosa piuttosto che un errore quando sbagli:

• La cartella deve esistere. Una cartella mancante fa fallire il caricamento con Document root '/no/such/place' does not exist.
• Le sottocartelle sono nomi di conto. Un estratto conto per Assets:US:BofA:Checking appartiene a <root>/Assets/US/BofA/Checking/. Un file che giace libero nella radice viene ignorato.
• Il conto deve essere aperto. I documenti trovati sotto un conto che il tuo registro non apre mai vengono saltati senza un avviso.
• I nomi dei file iniziano con una data, nella forma YYYY-MM-DD.description.ext (es., 2025-07-28.amazon-order.pdf). Qualsiasi altra cosa nella cartella viene ignorata.
• I percorsi possono essere assoluti o relativi al file di registro principale e l'opzione può essere ripetuta per diverse cartelle.

Sistema di Plugin​

Le funzionalità di Beancount possono essere estese con plugin.

Configurazione dei Plugin​

Un plugin viene caricato con una direttiva plugin autonoma, non con option. option "plugin" "..." fallisce con 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

Quel file si carica perché auto_accounts apre entrambi i conti per te; elimina la riga plugin e riporta Invalid reference to unknown account 'Expenses:Food:Coffee'. Un plugin che accetta configurazione la riceve come seconda stringa, plugin "module" "config". I plugin vengono eseguiti nell'ordine in cui li scrivi, dopo la fase documents di Beancount e prima delle sue fasi pad e balance — a meno che tu non imposti plugin_processing_mode su raw, che elimina del tutto queste fasi.

Limiti Tecnici e Vincoli​

Queste opzioni controllano aspetti tecnici del parser di Beancount.

Gestione delle Stringhe​

Puoi impostare un limite al numero di righe consentite in una stringa multilinea, così una virgoletta non terminata viene riportata vicino a dove l'hai digitata piuttosto che alla fine del file.

option "long_string_maxlines" "64"

Precisione dell'Interpolazione​

Per impostazione predefinita Beancount usa una tolleranza per due compiti diversi: riempire un importo mancante e decidere se la transazione è bilanciata. Attivare questa opzione usa la tolleranza dedotta più fine per il primo e quella più lasca per il secondo, il che impedisce agli importi interpolati di deviare.

option "use_precise_interpolation" "TRUE"

Non esiste alcuna opzione per tolleranze esplicite su una registrazione. L'unica sintassi di tolleranza esplicita che Beancount 3.2.3 ha è la tilde su una direttiva balance — 4.271 ~ 0.01 RGAGX — e non richiede alcuna opzione. Una tilde all'interno di una registrazione di transazione è un errore di sintassi.

Opzioni Deprecate e Rimosse​

Tre opzioni che guide più vecchie raccomandano ancora non esistono in Beancount 3.2.3. Ogni riga in questo blocco fa fallire il caricamento:

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

• experiment_explicit_tolerances — la sintassi ~ a livello di registrazione che abilitava è sparita; usa invece la tilde di una direttiva balance.
• use_legacy_fixed_tolerances — le tolleranze fisse 0.005/0.015 sono sparite; la tolleranza viene dedotta per transazione, regolata con tolerance_multiplier e inferred_tolerance_default.
• default_tolerance — sostituita da inferred_tolerance_default per il bilanciamento e display_precision per la resa.

Altri tre funzionano ancora ma riportano un errore di deprecazione, che è sufficiente per far fallire bea check:

• inferred_tolerance_multiplier — rinominata a tolerance_multiplier.
• allow_pipe_separator — accetta la vecchia | tra beneficiario e narrazione.
• allow_deprecated_none_for_tags_and_links — accetta un letterale None dove appartengono tag e link.

Le opzioni di Fava sono separate​

Tutto su questa pagina viene letto da Beancount stesso. Le impostazioni di Fava non sono affatto direttive option — sono direttive custom "fava-option" con una data e Beancount le ignora. Scrivere un'impostazione di Fava come option fallisce con Invalid option. Consulta Opzioni di Fava per quell'elenco.

Configurazione Raccomandata ✅​

Per la maggior parte degli utenti, la seguente configurazione fornisce un punto di partenza robusto e sensato. È un unico file e si carica.

; 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"

I commenti iniziano con ;. Un commento // è un errore di sintassi in Beancount e trascina con sé il resto del file.

Questa configurazione fornisce una solida base per un nuovo registro Beancount, garantendo una reportistica chiara, un controllo sensato della precisione e una struttura logica dei conti di patrimonio netto.