Beancount

3.2.2 verified Fri May 01 auth: no python

Double-entry accounting from text files. Beancount is a command-line tool and Python library that reads a plain-text ledger file and produces financial reports. Version 3.2.2, release cadence is irregular (~1-2 major releases per year). Requires Python >=3.9.

pip install beancount

Common errors

error TypeError: 'module' object is not callable ↓

cause Importing 'from beancount import load' attempts to call the module as a function.

fix

Use 'from beancount.loader import load'.

error KeyError: 'open' ↓

cause Trying to access an account that hasn't been opened in the ledger.

fix

Ensure the account is declared with 'open' directive before use.

error beancount.core.data.NoMatchError: No match for posting ↓

cause A transaction posting references an account that doesn't exist or is misspelled.

fix

Verify account names in the posting match exactly the declared accounts.

Warnings

breaking Beancount 3 dropped Python 3.8 support; requires Python >=3.9. ↓

fix Update Python to 3.9 or newer.

breaking In Beancount 3, the old 'from beancount import *' patterns no longer work; explicit imports from submodules are required. ↓

fix Update imports to use specific submodules (e.g., from beancount.loader import load).

gotcha Beancount's ledger format is whitespace-sensitive; tabs vs. spaces can cause parse errors. ↓

fix Use spaces (2 or 4) for indentation; avoid tab characters.

deprecated The 'beancount.core.inventory' API is deprecated in favor of 'beancount.core.amount' and 'beancount.core.position'. ↓

fix Migrate to using Amount and Position objects from beancount.core.amount and beancount.core.position.

Imports

load
wrong
```
from beancount import load
```
correct
```
from beancount.loader import load
```
load is not a top-level attribute; must import from the loader submodule.

RealAccount

wrong

from beancount.core.account import RealAccount

correct

from beancount.core.data import RealAccount

RealAccount is a data object, defined in beancount.core.data.

filter_txns

wrong

from beancount.core import filter_txns

correct

from beancount.core.realization import filter_txns

filter_txns is located in the realization module.

Quickstart

Load a Beancount ledger file and print the first five entries.

from beancount.loader import load
from beancount.printer import format_entry

# Load a ledger file (replace with actual path or use os.environ)
import os
ledger_path = os.environ.get('BEANCOUNT_LEDGER', 'example.bean')
entries, errors, options_map = load(ledger_path)
if errors:
    for e in errors:
        print(e)
# Print first 5 transactions
for entry in entries[:5]:
    print(format_entry(entry))