Forecasting Future Transactions in Beancount
Beancount can project future recurring transactions using the fava.plugins.forecast
plugin. This allows you to visualize the future impact of regular income and expenses, such as salaries, rent, and subscriptions, on your financial reports.
Step 1: Enable the Forecast Plugin
First, you need to enable the plugin by adding the following line to the top of your Beancount ledger file:
plugin "fava.plugins.forecast"
Step 2: Create a Forecast Transaction
To forecast a recurring transaction, create a single transaction entry using the #
flag (instead of *
or !
) and add a special forecast tag to the narration.
The basic structure looks like this:
YYYY-MM-DD # "Narration [FREQUENCY CONDITIONS]"
Account:One 100.00 USD
Account:Two -100.00 USD
The forecast plugin will use this entry as a template to generate future transactions in your reports.
Understanding the Forecast Syntax
The forecast tag in the narration follows a specific format: [FREQUENCY CONDITIONS]
.
Frequency
The FREQUENCY
part is mandatory and defines how often the transaction recurs. It must be in all caps.
DAILY
WEEKLY
MONTHLY
QUARTERLY
YEARLY
Example: A Monthly Rent Payment This transaction will be projected to occur on the 1st of every month, starting from January 2024.
2024-01-01 # "Rent payment [MONTHLY]"
Expenses:Housing:Rent 2500.00 USD
Assets:Checking -2500.00 USD
Conditions (Optional)
You can add optional CONDITIONS
to control the forecast's duration and pattern.
1. Set an End Date with UNTIL
Use UNTIL YYYY-MM-DD
to stop the forecast on a specific date.
- Example: A Gym membership that ends this year.
2024-01-15 # "Gym membership [MONTHLY UNTIL 2024-12-31]"
Expenses:Health:Gym 80.00 USD
Assets:Checking -80.00 USD
2. Limit Occurrences with REPEAT
Use REPEAT n TIMES
to generate the transaction a specific number of times.
- Example: A car loan with 36 remaining payments.
2024-01-25 # "Car payment [MONTHLY REPEAT 36 TIMES]"
Expenses:Transportation:CarPayment 450.00 USD
Liabilities:Auto-Loan -450.00 USD
3. Create Irregular Patterns with SKIP
Use SKIP n TIME/TIMES
to skip intervals. This is useful for things like bi-weekly paychecks.
- Example: A bi-weekly salary (occurs every two weeks).
2024-01-05 # "Bi-weekly salary [WEEKLY SKIP 1 TIME]"
Assets:Checking 3000.00 USD
Income:Salary -3000.00 USD
Practical Example: A Monthly Budget
You can combine multiple forecasts to project your entire budget, including various income and expense streams.
plugin "fava.plugins.forecast"
; === INCOME ===
2024-01-05 # "Bi-weekly salary [WEEKLY SKIP 1 TIME]"
Assets:Checking 3000.00 USD
Income:Salary -3000.00 USD
; === EXPENSES ===
2024-01-01 # "Rent [MONTHLY]"
Expenses:Housing:Rent 2500.00 USD
Assets:Checking -2500.00 USD
2024-01-01 # "Groceries [WEEKLY]"
Expenses:Food:Groceries 150.00 USD
Assets:Checking -150.00 USD
2024-01-15 # "Car Insurance [QUARTERLY REPEAT 4 TIMES]"
Expenses:Insurance:Auto 450.00 USD
Assets:Checking -450.00 USD
Once you add these entries, your reports, such as the Income Statement and Net Profit chart, will automatically include the projected data, giving you a clear view of your financial future.
Troubleshooting & Best Practices
-
Forecasts Not Appearing?
- Ensure
plugin "fava.plugins.forecast"
is in your ledger file. - Use the
#
flag for the transaction, not*
. - Check for typos in the frequency tag (e.g.,
[MONTHLY]
not[Monthly]
or[MONTLY]
).
- Ensure
-
Best Practices
- Be Descriptive: Use clear narrations so you know what each forecast is for.
- Review Regularly: Update your forecasts (e.g., for a salary increase or rent change) to keep them accurate.
- Use End Conditions: For transactions that aren't permanent (like loans or subscriptions), use
UNTIL
orREPEAT
to prevent them from forecasting indefinitely.