Options Configuration

Beancount's behavior is customized with option directives placed at the top of your main ledger file. These key-value pairs control the names of your root accounts, how much imbalance a transaction may carry, and which extensions run. ⚙️

Every option on this page was loaded against Beancount 3.2.3, and every error message quoted is the one that version prints. Beancount rejects an option it does not recognize — option "default_tolerance" "USD:0.01" fails with Invalid option: 'default_tolerance' — so an option copied from an older guide does not fail quietly. Run bea check on your file after changing anything here.

Core Configuration Options​

These options control the fundamental setup of your ledger.

Basic Settings​

These are some of the most common options you'll set.

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

• title: Sets the title for reports and web interfaces. Defaults to Beancount.
• render_commas: If true, numbers in reports are formatted with thousands separators (e.g., 1,000,000.00). Defaults to false. Any of 1, TRUE, true or yes reads as true; every other string reads as false.
• plugin_processing_mode: Either default (the default) or raw. Any other value fails with Error for option 'plugin_processing_mode'.

raw is not a milder version of default — it is the switch that turns off Beancount's own processing stages. Under default, Beancount runs beancount.ops.documents before your plugins and beancount.ops.pad and beancount.ops.balance after them. Under raw it runs only the plugins you list yourself, so pad directives are never applied and balance assertions are never checked:

; 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

Change that one line to default and the same file reports Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Use raw only when you are deliberately reimplementing those stages yourself.

Account Name Customization​

You can rename Beancount's five fundamental account types. This is not cosmetic. The option redefines which root names the parser accepts, so every account in your file has to use the new name, and the old one becomes invalid.

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

Leave a single posting on the old root and the file stops loading with Invalid account name: Assets:Banque:Courant. The five options are name_assets, name_liabilities, name_equity, name_income and name_expenses; each value must be a single capitalized word with no colon, or you get Error for option 'name_assets': Invalid root account name. Rename roots when you start a ledger, not halfway through one.

Equity Account Configuration​

Beancount synthesizes several equity accounts when it summarizes a period — opening balances, retained earnings and currency conversions. These options name them.

Each value is a leaf name, and Beancount joins it under name_equity for you. Writing the equity root yourself produces Equity:Equity:Opening-Balances, which is a different account from the one you meant.

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 the exception in this group: it takes a complete account name and is stored exactly as written, which is why Equity:Rounding above is correct and not a doubled prefix. It is also unset by default, and on Beancount 3.2.3 setting it has no effect on loading — see Precision & Tolerances for what actually happens to a residual.

Precision and Tolerance Settings​

These options control how much imbalance Beancount accepts in a transaction.

Default Tolerance Configuration​

Beancount infers a tolerance for every transaction from the number of decimal places in its postings. These three options adjust that inference.

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

• inferred_tolerance_default: A floor per currency, used when a transaction has no decimals to infer from. The syntax is <currency>:<number>, and * sets every currency at once. Repeat the option to set several.
• tolerance_multiplier: The fraction of the smallest digit that counts as tolerable, default 0.5. It is not a percentage bump: 1.2 makes every inferred tolerance 2.4 times the default one.
• infer_tolerance_from_cost: If true, postings held at cost widen the tolerance in the cost currency too. Off by default.

The old name inferred_tolerance_multiplier still sets the same value, but it reports Renamed to 'tolerance_multiplier'. as a load error, so bea check fails on a file that uses it. Rename it.

Booking Method​

This option sets the default rule for choosing which lot a reduction draws down. Give one account a different rule on its open directive.

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

Beancount 3.2.3 accepts exactly seven names: STRICT (the default), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO and AVERAGE. Anything else is rejected at load time with Error for option 'booking_method' — including SIMPLE and FULL, which are not booking methods and never were. AVERAGE is accepted here but has no implementation behind it; a reduction under it raises AVERAGE method is not supported. Inventory Management works through all seven on the same ledger.

Currency Management​

Proper currency configuration is vital for accurate reporting.

Operating Currency​

An operating currency is a currency you want reports to total in. Repeat the option to declare more than one; the values accumulate rather than replacing each other.

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

Declaring operating currencies tells reporting tools to give each one its own column. conversion_currency names the imaginary currency Beancount books conversions into at a rate of zero; it already defaults to NOTHING, and the only reason to set it is to pick a different placeholder that your ledger definitely never uses as a real commodity.

Document Management​

Beancount can link transactions to external files like receipts or invoices. The documents option gives it a folder to scan.

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

The path in that block is an illustration — substitute your own before running it. Only the first rule below is reported as an error; break any of the others and the file is simply never found:

• The folder must exist. A missing one fails the load with Document root '/no/such/place' does not exist.
• Sub-folders are account names. A statement for Assets:US:BofA:Checking belongs at <root>/Assets/US/BofA/Checking/. A file sitting loose at the root is ignored.
• The account must be open. Documents found under an account your ledger never opens are skipped without a warning.
• File names start with a date, in the form YYYY-MM-DD.description.ext (e.g., 2025-07-28.amazon-order.pdf). Anything else in the folder is ignored.
• Paths can be absolute or relative to the main ledger file, and the option may be repeated for several folders.

Plugin System​

Beancount's functionality can be extended with plugins.

Plugin Configuration​

A plugin is loaded with a standalone plugin directive, not with option. option "plugin" "..." fails with 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

That file loads because auto_accounts opens both accounts for you; delete the plugin line and it reports Invalid reference to unknown account 'Expenses:Food:Coffee'. A plugin that takes configuration receives it as a second string, plugin "module" "config". Plugins run in the order you write them, after Beancount's own documents stage and before its pad and balance stages — unless you set plugin_processing_mode to raw, which drops those stages entirely.

Technical Limits and Constraints​

These options control technical aspects of the Beancount parser.

String Handling​

You can set a limit on the number of lines allowed in a multi-line string, so an unterminated quote is reported near where you typed it rather than at the end of the file.

option "long_string_maxlines" "64"

Interpolation Precision​

By default Beancount uses one tolerance for two different jobs: filling in a missing amount, and deciding whether the transaction balances. Turning this on uses the finest inferred tolerance for the first and the loosest for the second, which stops interpolated amounts from drifting.

option "use_precise_interpolation" "TRUE"

There is no option for explicit tolerances on a posting. The only explicit-tolerance syntax Beancount 3.2.3 has is the tilde on a balance directive — 4.271 ~ 0.01 RGAGX — and it needs no option at all. A tilde inside a transaction posting is a syntax error.

Deprecated and Removed Options​

Three options that older guides still recommend do not exist in Beancount 3.2.3. Every line in this block fails the load:

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

• experiment_explicit_tolerances — the posting-level ~ syntax it enabled is gone; use a balance directive's tilde instead.
• use_legacy_fixed_tolerances — the fixed 0.005/0.015 tolerances are gone; tolerance is inferred per transaction, tuned with tolerance_multiplier and inferred_tolerance_default.
• default_tolerance — replaced by inferred_tolerance_default for balancing and display_precision for rendering.

Three more still work but report a deprecation error, which is enough to fail bea check:

• inferred_tolerance_multiplier — renamed to tolerance_multiplier.
• allow_pipe_separator — accepts the old | between payee and narration.
• allow_deprecated_none_for_tags_and_links — accepts a literal None where tags and links belong.

Fava Options Are Separate​

Everything on this page is read by Beancount itself. Fava's own settings are not option directives at all — they are custom "fava-option" directives with a date, and Beancount ignores them. Writing a Fava setting as an option fails with Invalid option. See Fava Options for that list.

Recommended Configuration ✅​

For most users, the following configuration provides a robust and sensible starting point. It is one file, and it loads.

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

Comments start with ;. A // comment is a syntax error in Beancount, and it takes the rest of the file down with it.

This setup provides a solid foundation for a new Beancount ledger, ensuring clear reporting, sensible precision control, and a logical equity account structure.