File and account structure

Files¶

Now you have a working instance of Beancount pre-filled with some example data and, presumably, some idea of Beancount basics. Maybe you also took a look at and explored the Fava interface.

These are the files as defined by the Lazy Beancount structure:

$ tree data
data
├── beancount_import_data
│   ├── monzo
│   ├── revolut_eur
│   ├── revolut_gbp
│   ├── revolut_usd
│   ├── wise_eur
│   ├── wise_gbp
│   └── wise_usd
├── beancount_import_output
│   ├── accounts.bean
│   ├── balance_accounts.bean
│   ├── ignored.bean
│   ├── prices.bean
│   └── transactions.bean
├── prices
│   ├── prices-2024-01-03.gen.bean
│   └── prices-2024-07-25.gen.bean
├── balances
│   ├── initial.gen.bean
│   ├── update-2024-01-05.gen.bean
│   ├── update-2024-01-12.gen.bean
├── accounts.bean
├── accounts_config.yml
├── beangrow-simple.config
├── commodities.bean
├── dashboards.yaml
├── docker-compose.yaml
├── importers_config.yml
├── main.bean
├── manual_transactions.bean
├── prices.bean
└── prices_config.yml

main.bean is an entry point of your Beancount setup. It contains configuration and also glues all other *.bean files together.

commodities.bean defines configuration of currencies, stocks, actuall commodities and such. How to use it will be described in more detail later.

Files under prices/ directory contain data about commodities prices and will be mostly semi-automatically fetched.

accounts.bean lists your accounts (add and review them in Defining accounts). The various types of accounts are Assets, Liabilities, Expenses, Income and Equity.

• Assets and Liabilities accounts will be introduced in the Stage I
• Expenses and Income in the Stage II
• Equity accounts are mostly used for technical purposes (e.g. starting and ending balances of the accounts)

Note from the author in one of the threads on Beancount that I found useful: "In a way, those categories are just a way to flag accounts as transient (income & expenses) vs. permanent (assets & liabilities), and positive balance (assets & expenses) vs. negative balance (liabiilties & income). Equity is mainly there to absord retained earnings and conversion entries ("trading accounts").".

Most YAML files are used to configure Lazy Beancount, except dashboards.yaml which is used to configure fava-dashboards (which is more or less generic but you can adjust specifics for your needs) and docker-compose.yaml that defines Docker configuration (and you likely don't need to modify it).

Account naming conventions are covered in Defining accounts.

How to migrate an existing Beancount setup¶

It should be pretty straightforward. You are not required to use any of the additional features but you can start benefitting from them immediately. You can also use your own account naming and other conventions but then you'll probably want to modify dashboards.yaml and other configs.

Probably the easiest path to start would be to include your ledger somewhere in the middle of main.bean and merge all the config-related instructions from it into main.bean making sure there are no conflicts/inconsistencies. As with pretty much everything else in this guide, you can leave data as it is and only use new libraries for adding new data, or migrate your old data in steps at your leisure.