Budgeting in Beancount
This guide explains how to set up, manage, and visualize per-account budgets using Beancount's custom
directives and the Fava web interface.
1. How to Set a Budget
Budgets are defined using a custom "budget"
directive in your Beancount file. The syntax is straightforward:
YYYY-MM-DD custom "budget" AccountName "interval" Amount CURRENCY
AccountName
: The specific expense or income account you want to budget for.interval
: The budget period. Must be one ofdaily
,weekly
,monthly
,quarterly
, oryearly
.Amount
: The target amount for the interval.
How it Works:
- A budget directive remains in effect from its date until another budget directive for the same account overrides it.
- Beancount and Fava break down all budgets into a daily equivalent, allowing them to calculate the total budgeted amount for any given date range.
Example:
; Set a daily budget for coffee
2024-01-01 custom "budget" Expenses:Food:Coffee "daily" 5.00 USD
; Set a monthly budget for groceries
2024-01-01 custom "budget" Expenses:Food:Groceries "monthly" 600.00 USD
; Set a yearly budget for vacations
2024-01-01 custom "budget" Expenses:Travel:Vacation "yearly" 3000.00 USD
To adjust a budget, simply add a new directive with a later date. For example, to increase the grocery budget starting in March:
2024-03-01 custom "budget" Expenses:Food:Groceries "monthly" 650.00 USD
2. Visualizing Budgets in Fava
Fava, the web interface for Beancount, automatically detects and displays your budgets in several key reports, allowing you to compare your actual spending to your targets:
- Income Statement: The Net Profit and Expenses charts will show budgeted vs. actual values.
- Changes (monthly): Shows the budgeted amount for each month.
- Balances (monthly): Shows the cumulative budgeted amount over time.
3. Advanced Budgeting Techniques
Budget Rollover The default budget system resets each period. To implement a "rollover" where unspent funds carry over, use a dedicated asset account to hold budgeted funds.
- Fund the budget account at the start of the period:
2024-02-01 * "Fund monthly entertainment budget"
Assets:Checking -200.00 USD
Assets:Budget:Entertainment 200.00 USD - Spend directly from this budget account:
The remaining balance in
2024-02-15 * "Movie night"
Expenses:Entertainment:Movies 30.00 USD
Assets:Budget:Entertainment -30.00 USDAssets:Budget:Entertainment
is your rollover amount.
Tracking Income Goals You can also set targets for your income accounts by using a negative budget amount. This allows Fava to track your earnings against your goals.
; Set monthly income targets
2024-01-01 custom "budget" Income:Salary "monthly" -5000.00 USD
2024-01-01 custom "budget" Income:Freelance "monthly" -1000.00 USD
4. Troubleshooting
If your budgets are not appearing in Fava, check the following:
- Date Format: Ensure dates are in
YYYY-MM-DD
format. - Account Names: The account name in the directive must exactly match the account name in your transactions.
- Interval Spelling: The interval must be one of the five valid options and in lowercase (e.g.,
"monthly"
). - Restart Fava: If you've recently added the directives, a restart of the Fava server may be needed to pick up the changes.