El comportament de Beancount es personalitza amb directives option col·locades a la part superior del teu fitxer principal de llibre. Aquests parells clau-valor controlen els noms dels teus comptes arrel, quant desequilibri pot contenir una transacció i quines extensions s'executen. ⚙️
Totes les opcions d'aquesta pàgina s'han carregat amb Beancount 3.2.3, i cada missatge d'error citat és el que imprimeix aquesta versió. Beancount rebutja una opció que no reconeix — option "default_tolerance" "USD:0.01" falla amb Invalid option: 'default_tolerance' —, de manera que una opció copiada d'una guia antiga no falla en silenci. Executa bea check sobre el teu fitxer després de canviar res aquí.
Opcions de configuració bàsica
Aquestes opcions controlen la configuració fonamental del teu llibre.
Configuració bàsica
Aquestes són algunes de les opcions més habituals que definiràs.
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"title: Estableix el títol per als informes i les interfícies web. Per defecte ésBeancount.render_commas: Si és cert, els números dels informes es formategen amb separadors de milers (per exemple,1,000,000.00). Per defecte és fals. Qualsevol de1,TRUE,trueoyeses llegeix com a cert; qualsevol altra cadena es llegeix com a fals.plugin_processing_mode: O bédefault(el valor per defecte) o béraw. Qualsevol altre valor falla ambError for option 'plugin_processing_mode'.
raw no és una versió més suau de default: és l'interruptor que desactiva les etapes de processament pròpies de Beancount. Amb default, Beancount executa beancount.ops.documents abans dels teus plugins i beancount.ops.pad i beancount.ops.balance després. Amb raw només s'executen els plugins que llistes tu mateix, de manera que les directives pad no s'apliquen mai i les assercions balance no es comproven mai:
; 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 USDCanvia aquesta línia per default i el mateix fitxer informa Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Utilitza raw només quan reimplementes deliberadament aquestes etapes tu mateix.
Personalització de noms de comptes
Pots canviar el nom dels cinc tipus fonamentals de comptes de Beancount. Això no és cosmètic. L'opció redefineix quins noms arrel accepta l'analitzador, de manera que tots els comptes del teu fitxer han d'utilitzar el nom nou, i el vell esdevé invàlid.
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 EURDeixa una sola anotació sobre l'arrel antiga i el fitxer deixa de carregar-se amb Invalid account name: Assets:Banque:Courant. Les cinc opcions són name_assets, name_liabilities, name_equity, name_income i name_expenses; cada valor ha de ser una única paraula amb majúscula inicial sense dos punts, o obteniu Error for option 'name_assets': Invalid root account name. Canvia el nom de les arrels quan comences un llibre, no a mig camí.
Configuració de comptes de patrimoni net
Beancount sintetitza diversos comptes de patrimoni net quan resumeix un període: saldos d'obertura, resultats retinguts i conversions de divises. Aquestes opcions els posen nom.
Cada valor és un nom de fulla, i Beancount el uneix sota name_equity per tu. Escriure l'arrel de patrimoni net tu mateix produeix Equity:Equity:Opening-Balances, que és un compte diferent del que volies dir.
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"| Opció | Fulla per defecte | Compte resultant |
|---|---|---|
account_previous_balances | Opening-Balances | Equity:Opening-Balances |
account_previous_earnings | Earnings:Previous | Equity:Earnings:Previous |
account_current_earnings | Earnings:Current | Equity:Earnings:Current |
account_previous_conversions | Conversions:Previous | Equity:Conversions:Previous |
account_current_conversions | Conversions:Current | Equity:Conversions:Current |
account_rounding és l'excepció d'aquest grup: pren un nom de compte complet i s'emmagatzema exactament com s'escriu, per això Equity:Rounding d'aquí dalt és correcte i no té un prefix duplicat. També està sense definir per defecte, i amb Beancount 3.2.3 definir-lo no té efecte en la càrrega; consulta Precisió i toleràncies per saber què passa realment amb un romanent.
Configuració de precisió i tolerància
Aquestes opcions controlen quant desequilibri accepta Beancount en una transacció.
Configuració de tolerància per defecte
Beancount infereix una tolerància per a cada transacció a partir del nombre de decimals de les seves anotacions. Aquestes tres opcions ajusten aquesta inferència.
option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"inferred_tolerance_default: Un mínim per divisa, utilitzat quan una transacció no té decimals d'on inferir. La sintaxi és<currency>:<number>, i*estableix totes les divises alhora. Repeteix l'opció per establir-ne diverses.tolerance_multiplier: La fracció del dígit més petit que compta com a tolerable, per defecte0.5. No és un augment percentual:1.2fa que cada tolerància inferida sigui 2,4 vegades la predeterminada.infer_tolerance_from_cost: Si és cert, les anotacions mantingudes a cost amplien la tolerància també en la divisa de cost. Desactivat per defecte.
El nom antic inferred_tolerance_multiplier encara estableix el mateix valor, però informa Renamed to 'tolerance_multiplier'. com a error de càrrega, de manera que bea check falla en un fitxer que l'utilitza. Canvia-li el nom.
Mètode d'assignació
Aquesta opció estableix la regla per defecte per triar quin lot redueix una reducció. Dóna a un compte una regla diferent a la seva directiva open.
; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"Beancount 3.2.3 accepta exactament set noms: STRICT (el predeterminat), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO i AVERAGE. Qualsevol altre es rebutja en temps de càrrega amb Error for option 'booking_method', incloent-hi SIMPLE i FULL, que no són mètodes d'assignació i mai no ho han estat. AVERAGE s'accepta aquí però no té cap implementació darrere; una reducció amb aquest mètode llança AVERAGE method is not supported. Gestió d'inventaris treballa els set amb el mateix llibre.
Gestió de divises
Una configuració correcta de les divises és vital per a informes precisa.
Moneda operativa
Una moneda operativa és una divisa en la qual vols que els informes totalitzin. Repeteix l'opció per declarar-ne més d'una; els valors s'acumulen en lloc de substituir-se.
option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"Declarar monedes operatives diu a les eines d'informes que donin a cadascuna la seva pròpia columna. conversion_currency nomena la divisa imaginària en la qual Beancount enregistra les conversions a un ritme de zero; ja té per defecte NOTHING, i l'única raó per establir-la és triar un altre marcador de posició que el teu llibre definitivament no utilitzi mai com a mercaderia real.
Gestió de documents
Beancount pot enllaçar transaccions a fitxers externs com rebuts o factures. L'opció documents li dóna una carpeta per escanejar.
option "documents" "/home/user/Documents/beancount"El camí d'aquest bloc és il·lustratiu: substituïu-lo pel vostre abans d'executar-lo. Només la primera regla de sota es reporta com a error; incompleix qualsevol de les altres i el fitxer simplement no es troba mai:
- La carpeta ha d'existir. Si no existeix, la càrrega falla amb
Document root '/no/such/place' does not exist. - Les subcarpetes són noms de comptes. Un extracte per a
Assets:US:BofA:Checkingpertany a<root>/Assets/US/BofA/Checking/. Un fitxer solt a l'arrel s'ignora. - El compte ha d'estar obert. Els documents trobats sota un compte que el teu llibre no obre mai s'ometen sense cap avís.
- Els noms de fitxer comencen amb una data, en la forma
YYYY-MM-DD.description.ext(per exemple,2025-07-28.amazon-order.pdf). Qualsevol altra cosa a la carpeta s'ignora. - Els camins poden ser absoluts o relatius al fitxer principal del llibre, i l'opció es pot repetir per a diverses carpetes.
Sistema de plugins
La funcionalitat de Beancount es pot ampliar amb plugins.
Configuració de plugins
Un plugin es carrega amb una directiva plugin independent, no amb option. option "plugin" "..." falla amb 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 USDAquest fitxer es carrega perquè auto_accounts obre els dos comptes per tu; elimina la línia plugin i informa Invalid reference to unknown account 'Expenses:Food:Coffee'. Un plugin que pren configuració la rep com una segona cadena, plugin "module" "config". Els plugins s'executen en l'ordre en què els escrius, després de l'etapa documents pròpia de Beancount i abans de les seves etapes pad i balance, tret que estableixis plugin_processing_mode a raw, que elimina aquestes etapes completament.
Límits tècnics i restriccions
Aquestes opcions controlen aspectes tècnics de l'analitzador de Beancount.
Gestió de cadenes
Pots establir un límit al nombre de línies permeses en una cadena multilínia, perquè una citació sense tancar es reporti a prop d'on l'has escrita en lloc de al final del fitxer.
option "long_string_maxlines" "64"Precisió d'interpolació
Per defecte, Beancount utilitza una tolerància per a dues tasques diferents: omplir un import que falta i decidir si la transacció quadra. Activar això utilitza la tolerància inferida més fina per a la primera i la més àmplia per a la segona, cosa que evita que els imports interpolats es desviïn.
option "use_precise_interpolation" "TRUE"No hi ha cap opció per a toleràncies explícites en una anotació. L'única sintaxi de tolerància explícita que té Beancount 3.2.3 és la titlla en una directiva balance — 4.271 ~ 0.01 RGAGX — i no necessita cap opció. Una titlla dins d'una anotació de transacció és un error de sintaxi.
Opcions obsoletes i eliminades
Tres opcions que les guies antigues encara recomanen no existeixen a Beancount 3.2.3. Cada línia d'aquest bloc falla la càrrega:
option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"experiment_explicit_tolerances— la sintaxi~a nivell d'anotació que habilitava ha desaparegut; utilitza la titlla d'una directivabalanceen lloc seu.use_legacy_fixed_tolerances— les toleràncies fixes0.005/0.015han desaparegut; la tolerància s'infereix per transacció, ajustada ambtolerance_multiplieriinferred_tolerance_default.default_tolerance— substituïda perinferred_tolerance_defaultper al quadrament idisplay_precisionper al renderitzat.
Tres més encara funcionen però informen un error d'obsolescència, cosa que n'hi ha prou per fer fallar bea check:
inferred_tolerance_multiplier— reanomenada atolerance_multiplier.allow_pipe_separator— accepta el|antic entre beneficiari i narració.allow_deprecated_none_for_tags_and_links— accepta unNoneliteral on van les etiquetes i els enllaços.
Les opcions de Fava són independents
Tot el que hi ha en aquesta pàgina ho llegeix Beancount mateix. La configuració pròpia de Fava no són directives option en absolut: són directives custom "fava-option" amb una data, i Beancount les ignora. Escriure una configuració de Fava com a option falla amb Invalid option. Consulta Opcions de Fava per a aquesta llista.
Configuració recomanada ✅
Per a la majoria d'usuaris, la configuració següent proporciona un punt de partida sòlid i raonable. És un sol fitxer, i es carrega.
; 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"Els comentaris comencen amb ;. Un comentari // és un error de sintaxi a Beancount, i s'emporta la resta del fitxer amb ell.
Aquesta configuració proporciona una base sòlida per a un nou llibre de Beancount, assegurant informes clars, un control de precisió raonable i una estructura lògica de comptes de patrimoni net.