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 of daily, weekly, monthly, quarterly, or yearly.
• 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.

1. 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

2. Spend directly from this budget account:

   2024-02-15 * "Movie night"
     Expenses:Entertainment:Movies      30.00 USD
     Assets:Budget:Entertainment       -30.00 USD

   The remaining balance in Assets: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:

1. Date Format: Ensure dates are in YYYY-MM-DD format.
2. Account Names: The account name in the directive must exactly match the account name in your transactions.
3. Interval Spelling: The interval must be one of the five valid options and in lowercase (e.g., "monthly").
4. Restart Fava: If you've recently added the directives, a restart of the Fava server may be needed to pick up the changes.