Lazy Beancount

https://lazy-beancount.xyz/
Admin
Lazy Beancount is an opinionated guide on how to start and continue tracking personal finances using...
Tokens:10,111
Snippets:165
Trust Score:7.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install beancount-importers Locally

Source: https://lazy-beancount.xyz/stage2_expenses/writing_importer

Navigate to the cloned directory and install the importers in editable mode using pip. This is necessary to use the importer scripts.

```bash
cd beancount-importers
pip install -e .

```

--------------------------------

### Run Lazy Beancount Docker Container

Source: https://lazy-beancount.xyz/setup/setup

Navigate to the example data directory and start the Docker Compose service to run Lazy Beancount. This command also sets the User ID and Group ID for the container.

```bash
cd lazy-beancount/example_data
env UID=$(id -u) GID=$(id -g) docker compose up

```

--------------------------------

### Clone the beancount-importers Repository

Source: https://lazy-beancount.xyz/stage2_expenses/writing_importer

Clone the repository to get the importer code. Ensure you have Git installed.

```bash
git clone https://github.com/Evernight/beancount-importers.git

```

--------------------------------

### Querying Beancount Ledger with BQL and Pandas

Source: https://lazy-beancount.xyz/stage4_improvements/overview

This script demonstrates how to load a Beancount ledger, execute a BQL query to aggregate expenses, and process the results into a pandas DataFrame for further analysis. Ensure you have the 'beancount' and 'pandas' libraries installed.

```python
from beancount import loader
from beancount.query import query
import pandas as pd

q = """
    SELECT year, month, CONVERT(SUM(position), 'USD', LAST(date)) AS value
    WHERE account ~ '^Expenses:EatingOut' AND NOT 'travel' IN tags AND year >= {}
    GROUP BY year, month
"
""
entries, errors, options_map = loader.load_file('main.bean')
row_types, rows = query.run_query(entries, options_map, q, 2024)
df = pd.DataFrame(rows)
df['value'] = df['value'].map(lambda v: v.get_only_position().units.number)

```

--------------------------------

### Original Imported Beancount Transaction

Source: https://lazy-beancount.xyz/stage4_improvements/overview

This is an example of a transaction as it might be initially imported. It shows a single expense category.

```beancount
2024-03-11 * "Store" "Store purchase at XXXXXXX" ^tr_id12345
    Assets:Bank:Cash   -75.2 USD
        date: 2024-03-11
        source_desc: "Store purchase at XXXXXXX"
    Expenses:Shopping 75.2 USD


```

--------------------------------

### Manual Investment Transactions

Source: https://lazy-beancount.xyz/stage3_investments/overview

Example of manually entering buy and sell transactions for stocks, including cost basis, commissions, and profit/loss. Useful when automatic importing is not feasible or for detailed record-keeping.

```beancount
2024-04-11 * "Buy SPY"
  Assets:MyStockBroker:SPY                                    3 SPY {517.9 USD}
  Assets:MyStockBroker:Cash                            -1556.12 USD
  Expenses:MyStockBroker:Commissions                       2.42 USD

2024-06-17 * "Sell SPY"
  Assets:MyStockBroker:SPY                                   -2 SPY {} @ 547 USD
  Assets:MyStockBroker:Cash                             1090.99 USD
  Expenses:MyStockBroker:Commissions                       3.01 USD
  Income:MyStockBroker:PnL

```

--------------------------------

### Record Refund for Shared Expense

Source: https://lazy-beancount.xyz/stage4_improvements/overview

Example of a transaction recording a refund for a previously shared expense, using a similar tag structure '#qs-GiftForBob-100p' to denote the full refund amount.

```beancount
2024-13-12 * "Return of Peter's share for Bob's gift" #qs-GiftForBob-100p
  Assets:Physical:Cash  -37.5 USD
  Expenses:FullyShared   37.5 USD
```

--------------------------------

### Record Shared Expense Transaction

Source: https://lazy-beancount.xyz/stage4_improvements/overview

Example of a transaction for a shared gift, marking it with a custom tag '#qs-GiftForBob-75p' and splitting the cost across an asset and an expense account.

```beancount
2024-03-10 * "Gift for Bob shared by 4 people" #qs-GiftForBob-75p
  Assets:Bank:Cash  -150 USD
  Expenses:FullyShared   150 USD
```

--------------------------------

### Edited Beancount Transaction for Better Categorization

Source: https://lazy-beancount.xyz/stage4_improvements/overview

This example demonstrates how to edit an imported transaction to split a single expense into multiple categories and add tags for improved tracking and organization.

```beancount
2024-03-11 * "Store" "Store purchase at XXXXXXX" ^tr_id12345 #irregular #share-Alice
    Assets:Bank:Cash   -75.2 USD
        date: 2024-03-11
        source_desc: "Store purchase at XXXXXXX"
    Expenses:Shopping 15 USD
    Expenses:Gifts 20 USD
    Expences:Groceries


```

--------------------------------

### Fetching Conversion Rates with bean-price

Source: https://lazy-beancount.xyz/stage1_totals/defining_currencies

Use the `bean-price` command-line tool to fetch conversion rates for a specific date. The output can be directly inserted into your Beancount price files.

```bash
PYTHONPATH=PYTHONPATH:. bean-price data/main.bean -i --date=2023-12-03
```

--------------------------------

### Lazy Beancount Project File Structure

Source: https://lazy-beancount.xyz/setup/overview

Illustrates the directory and file layout for a typical Lazy Beancount project, showing where import data, generated files, and configuration reside.

```tree
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

```

--------------------------------

### Enabling Indirect Conversions with a Plugin

Source: https://lazy-beancount.xyz/stage1_totals/defining_currencies

Use the `beancount-generate-base-ccy-prices` plugin to enable indirect currency conversions in the Fava interface. This requires specifying the base currency for conversions.

```beancount
plugin "beancount-generate-base-ccy-prices.generate_base_ccy_prices" "EUR"
```

--------------------------------

### Run a Specific Bank Importer

Source: https://lazy-beancount.xyz/stage2_expenses/writing_importer

Execute an importer script for a specific bank (e.g., Wise) to extract data from a CSV file and output it in Beancount format. The output is redirected to a .bean file.

```bash
python3 -m beancount_importers.import_wise extract <csv_file> > wise.bean

```

--------------------------------

### Configure beancount_share Plugin for Quick Shared Expenses

Source: https://lazy-beancount.xyz/stage4_improvements/overview

This configuration sets up the beancount_share plugin to manage shared expenses. It defines names for marking transactions and metadata, an open date for accounts, and the specific liability accounts to use for debtors and creditors.

```beancount
plugin "beancount_share.share" "{
  'mark_name': 'qs',
  'meta_name': 'shared',
  'open_date': '1970-01-01',
  'account_debtors': 'Liabilities:QuickShare',
  'account_creditors': 'Liabilities:QuickShare',
}"
```

--------------------------------

### Clone Lazy Beancount Repository

Source: https://lazy-beancount.xyz/setup/setup

Use this command to download the Lazy Beancount project files from GitHub.

```bash
git clone https://github.com/Evernight/lazy-beancount

```

--------------------------------

### Run Beancount Importer Script

Source: https://lazy-beancount.xyz/stage2_expenses/writing_importer

Execute the beancount-import script to process CSV files and prepare transactions for import. Ensure the PYTHONPATH is set correctly and specify an output directory for the generated Beancount files.

```bash
PYTHONPATH=.:beangulp python3 beancount-importers/beancount_import_run.py --output_dir beancount_import_beans
```

--------------------------------

### Run Beancount Importer Directly

Source: https://lazy-beancount.xyz/stage2_expenses/writing_importer

Execute a Beancount importer directly from the command line for testing and debugging purposes. This is useful for verifying changes to column mappings or categorizer functions.

```bash
python3 -m beancount_importers.import_wise extract <csv_file>
```

--------------------------------

### Defining Commodities (Currencies)

Source: https://lazy-beancount.xyz/stage1_totals/defining_currencies

Define custom commodities (currencies) with their price sources and optional asset class metadata. Ensure the price source is valid for fetching conversion rates.

```beancount
1970-01-01 commodity GBP
  price: "USD:yahoo/GBPUSD=X"
  asset_class: "currency"

1970-01-01 commodity USD
  price: "GBP:yahoo/USDGBP=X"
  asset_class: "currency"

1970-01-01 commodity EUR
  price: "USD:yahoo/EURUSD=X"
  asset_class: "currency"
```

--------------------------------

### Configuring Operating Currencies

Source: https://lazy-beancount.xyz/stage1_totals/defining_currencies

Set the primary operating currencies for your Beancount ledger. These currencies can be selected in the Fava interface for reporting and conversions.

```beancount
option "operating_currency" "USD"
option "operating_currency" "GBP"
option "operating_currency" "EUR"
```
Tokens:
Raw