Options Configuration in Beancount

Beancount's behavior can be customized using option directives placed at the top of your main ledger file. These key-value pairs control everything from the names of your root accounts to how currency conversions are handled. Properly configuring these options is essential for tailoring Beancount to your specific needs. ⚙️

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 "render_commas" "TRUE"
option "plugin_processing_mode" "raw"

• title: Sets the title for reports and web interfaces.
• render_commas: If TRUE, numbers in reports will be formatted with thousands separators (e.g., 1,000,000.00).
• plugin_processing_mode: Controls how plugins are loaded. raw loads only the plugins you explicitly specify, while default includes a standard set of helpful plugins.

Account Name Customization

You can rename Beancount's five fundamental account types. This is purely cosmetic and changes how they appear in reports.

option "name_assets" "Assets"
option "name_liabilities" "Liabilities"
option "name_equity" "Equity"
option "name_income" "Income"
option "name_expenses" "Expenses"

Equity Account Configuration

Beancount automatically creates several special equity accounts to handle opening balances and income calculations. You can specify custom names for these accounts.

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

• account_previous_balances: The account used to inject opening balances into your ledger.
• account_current_earnings: The account that accumulates all income and expense totals for the current period, effectively calculating your net income.
• account_rounding: The account where small discrepancies from automated rounding are posted.

Precision and Tolerance Settings

These options control how Beancount handles rounding and small imbalances in transactions.

Default Tolerance Configuration

Beancount can automatically infer a tolerance for transactions with multiple currencies or costs, allowing for small rounding differences without causing errors.

option "inferred_tolerance_default" "USD:0.01"
option "inferred_tolerance_multiplier" "1.1"
option "infer_tolerance_from_cost" "True"

• inferred_tolerance_default: Sets the default tolerance for a given currency. You can use *:0.5 to set a default for all currencies.
• inferred_tolerance_multiplier: A factor applied to the tolerance to provide a slightly larger margin of error.
• infer_tolerance_from_cost: If True, the tolerance will be inferred from the number of digits in the cost.

Booking Method

This option defines how Beancount handles transactions where one leg is inferred.

option "booking_method" "SIMPLE"

• SIMPLE: Allows only one commodity to be automatically balanced per transaction. This is the recommended and most common method.
• FULL: Allows multiple commodities to be balanced, which is a more complex and rarely needed method.

Currency Management

Proper currency configuration is vital for accurate reporting.

Operating Currency

You can declare one or more "operating currencies." These are the main currencies you transact in and want to see in reports.

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

Declaring operating currencies tells Beancount to create dedicated columns for them in reports, making it easy to see your financial position in your most-used currencies. Setting conversion_currency to NOTHING disables the automatic conversion column, which is often preferred for cleaner reports.

Document Management

Beancount can link transactions to external files like receipts or invoices. The documents option specifies the root folder(s) where these files are stored.

option "documents" "/path/to/documents/archive"

Requirements:

• Files must be named using the format YYYY-MM-DD.description.ext (e.g., 2025-07-28.amazon-order.pdf).
• You can specify multiple documents options for different folders.
• Paths can be absolute or relative to the main ledger file.

Plugin System

Beancount's functionality can be extended with plugins.

Plugin Configuration

You enable a plugin by specifying its module path.

option "plugin" "beancount.plugins.module_name"

As mentioned earlier, the plugin_processing_mode option controls whether Beancount loads just your specified plugins (raw) or a default set as well (default).

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 to prevent parsing errors.

option "long_string_maxlines" "64"

Experimental Features

Beancount sometimes includes experimental features that you can enable with an option. For example, to enable explicit tolerance syntax:

option "experiment_explicit_tolerances" "True"

This allows you to specify tolerance directly in a transaction posting, like this: 532.23 ~ 0.001 USD.

System Behavior Controls

These options are for maintaining compatibility or specific system behaviors.

Legacy Support

This option enables the old, fixed tolerance values for backward compatibility with older ledgers.

option "use_legacy_fixed_tolerances" "True"

The fixed legacy tolerances were:

• Balance/Pad directives: 0.015 units
• Transactions: 0.005 units

Recommended Configuration ✅

For most users, the following configuration provides a robust and sensible starting point.

Basic Setup

option "title" "Personal Ledger"
option "operating_currency" "USD"  // Change to your primary currency
option "documents" "/home/user/Documents/beancount" // Change to your documents path
option "render_commas" "TRUE"

Precision Control

option "inferred_tolerance_default" "USD:0.01" // Change to your primary currency
option "inferred_tolerance_multiplier" "1.1"
option "infer_tolerance_from_cost" "True"

Account Structure

option "account_previous_balances" "Equity:Opening-Balances"
option "account_current_earnings" "Equity:Current-Earnings"
option "account_rounding" "Expenses:Rounding"

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