# Configure Beancount ledgers with option directives

Beancount's behavior is customized with `option` directives placed at the top of [your main ledger file](https://beancount.io/docs/Tips/multi-file-support). 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.

```bean
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**:

```bean
; 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](/blog/2026/04/08/debits-and-credits-explained-a-plain-english-guide-for-small-business-owners). **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.

```bean
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.

```bean
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"
```

| Option | Default leaf | Resulting account |
| --- | --- | --- |
| `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` 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](https://beancount.io/docs/Basics/precision) 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](https://beancount.io/docs/Basics/precision) for every transaction from the number of decimal places in its postings. These three options adjust that inference.

```bean
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.

```bean
; 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](https://beancount.io/docs/Basics/inventories) 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.

```bean
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.

```bean
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`.

```bean
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.

```bean
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.

```bean
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:

```bean
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](https://beancount.io/docs/Basics/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.

```bean
; 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](https://beancount.io/docs/Basics/getting-started), ensuring clear reporting, sensible precision control, and a logical equity account structure.
