Optieconfiguratie

Het gedrag van Beancount wordt aangepast met option-instructies die bovenaan uw hoofd grootboekbestand worden geplaatst. Deze sleutel-waardeparen bepalen de namen van uw hoofdcategorieën, hoeveel afwijking een transactie mag hebben, en welke extensies worden uitgevoerd. ⚙️

Elke optie op deze pagina is getest met Beancount 3.2.3, en elk foutbericht is dat wat deze versie weergeeft. Beancount wijst een optie af die het niet herkent — option "default_tolerance" "USD:0.01" faalt met Invalid option: 'default_tolerance' — dus een optie uit een oudere handleiding faalt niet stil. Voer bea check uit op uw bestand nadat u iets hebt gewijzigd.

Basisinstellingen​

Deze opties bepalen de fundamentele opzet van uw grootboek.

Algemene instellingen​

Dit zijn enkele van de meest voorkomende opties die u instelt.

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

• title: Stelt de titel in voor rapporten en webinterfaces. Standaardwaarde is Beancount.
• render_commas: Indien true, worden getallen in rapporten opgemaakt met duizendtalseparatoren (bijv. 1,000,000.00). Standaardwaarde is false. Elke van 1, TRUE, true of yes wordt als true gelezen; elke andere string als false.
• plugin_processing_mode: Ofwel default (de standaard) ofwel raw. Elke andere waarde faalt met Error for option 'plugin_processing_mode'.

raw is geen mildere versie van default — het is de schakelaar die de eigen verwerkingsfasen van Beancount uitschakelt. Onder default voert Beancount beancount.ops.documents uit vóór uw plugins en beancount.ops.pad en beancount.ops.balance erna. Onder raw voert het alleen de plugins uit die u zelf opgeeft, dus pad-instructies worden nooit toegepast en balance-controles worden nooit uitgevoerd:

; 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

Verander die ene regel naar default en hetzelfde bestand rapporteert Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Gebruik raw alleen wanneer u die fasen zelf opnieuw implementeert.

Aanpassing van categorienamen​

U kunt de vijf fundamentele categorietypen van Beancount hernoemen. Dit is niet cosmetisch. De optie bepaalt welke rootnamen de parser accepteert, dus elke categorie in uw bestand moet de nieuwe naam gebruiken, en de oude wordt ongeldig.

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

Laat een enkele boeking op de oude root staan en het bestand stopt met laden met Invalid account name: Assets:Banque:Courant. De vijf opties zijn name_assets, name_liabilities, name_equity, name_income en name_expenses; elke waarde moet een enkel woord met een hoofdletter zijn, zonder dubbele punt, anders krijgt u Error for option 'name_assets': Invalid root account name. Hernoem roots wanneer u een grootboek start, niet halverwege.

Configuratie van eigen vermogen​

Beancount genereert verschillende eigenvermogenrekeningen wanneer het een periode samenvat — openingsbalansen, ingehouden winsten en valutaomrekeningen. Deze opties benoemen ze.

Elke waarde is een subcategorienaam, en Beancount voegt deze onder name_equity voor u samen. Als u de eigen vermogen-root zelf schrijft, produceert u Equity:Equity:Opening-Balances, wat een andere rekening is dan u bedoelde.

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 is de uitzondering in deze groep: het neemt een volledige categorienaam en wordt exact opgeslagen zoals geschreven, daarom is Equity:Rounding hierboven correct en geen dubbel voorvoegsel. Het is ook standaard niet ingesteld, en bij Beancount 3.2.3 heeft het instellen ervan geen effect op het laden — zie Precisie & Toleranties voor wat er werkelijk gebeurt met een restverschil.

Precisie- en tolerantie-instellingen​

Deze opties bepalen hoeveel afwijking Beancount accepteert in een transactie.

Standaard tolerantieconfiguratie​

Beancount leidt een tolerantie af voor elke transactie uit het aantal decimalen in de postingen. Deze drie opties passen die afleiding aan.

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

• inferred_tolerance_default: Een ondergrens per valuta, gebruikt wanneer een transactie geen decimalen heeft om uit af te leiden. De syntaxis is <currency>:<number>, en * stelt elke valuta tegelijk in. Herhaal de optie om meerdere in te stellen.
• tolerance_multiplier: De fractie van het kleinste cijfer dat als tolereerbaar telt, standaard 0.5. Het is geen procentuele verhoging: 1.2 maakt elke afgeleide tolerantie 2,4 keer de standaard.
• infer_tolerance_from_cost: Indien true, verbreedt een post tegen kostprijs de tolerantie ook in de kostvaluta. Standaard uit.

De oude naam inferred_tolerance_multiplier stelt nog steeds dezelfde waarde in, maar rapporteert Renamed to 'tolerance_multiplier'. als laadfout, dus bea check faalt op een bestand dat het gebruikt. Hernoem het.

Boekingsmethode​

Deze optie bepaalt de standaardregel voor het kiezen welke partij wordt afgeboekt. Geef één rekening een andere regel via de open-instructie.

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

Beancount 3.2.3 accepteert precies zeven namen: STRICT (de standaard), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO en AVERAGE. Al het andere wordt afgewezen bij het laden met Error for option 'booking_method' — inclusief SIMPLE en FULL, die geen boekingsmethoden zijn en dat nooit waren. AVERAGE wordt hier geaccepteerd maar heeft geen implementatie erachter; een afboeking eronder geeft AVERAGE method is not supported. Voorraadbeheer werkt door alle zeven op hetzelfde grootboek.

Valutabeheer​

Een juiste valutaconfiguratie is essentieel voor nauwkeurige rapportage.

Functionele valuta​

Een functionele valuta is een valuta waarin u rapporten wilt totaliseren. Herhaal de optie om er meer dan één te declareren; de waarden stapelen zich op in plaats van elkaar te vervangen.

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

Het declareren van functionele valuta's vertelt rapportagetools om elke valuta een eigen kolom te geven. conversion_currency benoemt de denkbeeldige valuta waarin Beancount conversies boekt tegen een koers van nul; het standaard is NOTHING, en de enige reden om het in te stellen is een andere tijdelijke aanduiding te kiezen die uw grootboek beslist nooit als echte grondstof gebruikt.

Documentbeheer​

Beancount kan transacties koppelen aan externe bestanden zoals bonnen of facturen. De optie documents geeft het een map om te scannen.

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

Het pad in dat blok is een illustratie — vervang het door uw eigen pad voordat u het uitvoert. De regels zijn streng en elk ervan is een stille no-op in plaats van een fout wanneer u het verkeerd doet:

• De map moet bestaan. Een ontbrekende map faalt bij het laden met Document root '/no/such/place' does not exist.
• Submappen zijn categorienamen. Een verklaring voor Assets:US:BofA:Checking hoort thuis in <root>/Assets/US/BofA/Checking/. Een bestand dat los op de root ligt, wordt genegeerd.
• De rekening moet geopend zijn. Documenten gevonden onder een rekening die uw grootboek nooit opent, worden overgeslagen zonder waarschuwing.
• Bestandsnamen beginnen met een datum, in de vorm YYYY-MM-DD.description.ext (bijv. 2025-07-28.amazon-order.pdf). Al het andere in de map wordt genegeerd.
• Paden kunnen absoluut zijn of relatief ten opzichte van het hoofd grootboekbestand, en de optie kan worden herhaald voor meerdere mappen.

Pluginsysteem​

De functionaliteit van Beancount kan worden uitgebreid met plugins.

Pluginconfiguratie​

Een plugin wordt geladen met een zelfstandige plugin-instructie, niet met option. option "plugin" "..." faalt met 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

Dat bestand laadt omdat auto_accounts beide rekeningen voor u opent; verwijder de plugin-regel en het rapporteert Invalid reference to unknown account 'Expenses:Food:Coffee'. Een plugin die configuratie nodig heeft, ontvangt deze als tweede string, plugin "module" "config". Plugins worden uitgevoerd in de volgorde waarin u ze schrijft, na de eigen documents-fase van Beancount en vóór de pad- en balance-fasen — tenzij u plugin_processing_mode op raw zet, wat die fasen volledig laat vervallen.

Technische limieten en beperkingen​

Deze opties beheren technische aspecten van de Beancount-parser.

Stringafhandeling​

U kunt een limiet instellen op het aantal toegestane regels in een meerregelige string, zodat een niet-afgesloten aanhalingsteken wordt gerapporteerd in de buurt van waar u het typte in plaats van aan het einde van het bestand.

option "long_string_maxlines" "64"

Interpolatieprecisie​

Standaard gebruikt Beancount één tolerantie voor twee verschillende taken: het invullen van een ontbrekend bedrag en het bepalen of de transactie in evenwicht is. Dit inschakelen gebruikt de fijnste afgeleide tolerantie voor de eerste en de ruimste voor de tweede, wat voorkomt dat geïnterpoleerde bedragen afdrijven.

option "use_precise_interpolation" "TRUE"

Er is geen optie voor expliciete toleranties op een post. De enige expliciete tolerantiesyntaxis die Beancount 3.2.3 heeft, is de tilde op een balance-instructie — 4.271 ~ 0.01 RGAGX — en die heeft helemaal geen optie nodig. Een tilde binnen een transactiepost is een syntaxisfout.

Verouderde en verwijderde opties​

Drie opties die oudere handleidingen nog aanbevelen, bestaan niet in Beancount 3.2.3. Elke regel in dit blok faalt bij het laden:

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

• experiment_explicit_tolerances — de postniveau-~-syntaxis die het inschakelde is verdwenen; gebruik in plaats daarvan de tilde van een balance-instructie.
• use_legacy_fixed_tolerances — de vaste toleranties van 0.005/0.015 zijn verdwenen; tolerantie wordt per transactie afgeleid, afgestemd met tolerance_multiplier en inferred_tolerance_default.
• default_tolerance — vervangen door inferred_tolerance_default voor het balanceren en display_precision voor weergave.

Drie andere werken nog maar rapporteren een verouderingsfout, wat voldoende is om bea check te laten falen:

• inferred_tolerance_multiplier — hernoemd naar tolerance_multiplier.
• allow_pipe_separator — accepteert de oude | tussen begunstigde en omschrijving.
• allow_deprecated_none_for_tags_and_links — accepteert een letterlijke None waar tags en links horen.

Fava-opties zijn apart​

Alles op deze pagina wordt door Beancount zelf gelezen. Fava's eigen instellingen zijn helemaal geen option-instructies — het zijn custom "fava-option"-instructies met een datum, en Beancount negeert ze. Het schrijven van een Fava-instelling als een option faalt met Invalid option. Zie Fava-opties voor die lijst.

Aanbevolen configuratie ✅​

Voor de meeste gebruikers biedt de volgende configuratie een robuust en verstandig startpunt. Het is één bestand en het laadt.

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

Opmerkingen beginnen met ;. Een //-opmerking is een syntaxisfout in Beancount en neemt de rest van het bestand mee naar beneden.

Deze opzet biedt een solide basis voor een nieuw Beancount-grootboek, en zorgt voor duidelijke rapportage, verstandige precisiecontrole en een logische eigenvermogenstructuur.