Quick Start

Ready to take control of your finances? This guide will get you up and running with Beancount in minutes. You'll learn how to create your first ledger, set up essential accounts, and record your first transactions.

Explore the live ledger →

Initial Setup​

Creating Your First Ledger​

; Basic structure for a new ledger
2024-01-01 open Assets:Checking
2024-01-01 open Equity:Opening-Balances
 
2024-01-02 * "Initial Deposit"
  Assets:Checking           100.00 USD
  Equity:Opening-Balances

Essential Configuration​

option "title" "Personal Finance Ledger"
option "operating_currency" "USD"

File Organization​

Recommended Structure​

; 1. Configuration Options
option "title" "Personal Ledger"
option "operating_currency" "USD"
 
; 2. Account Declarations
2024-01-01 open Assets:Checking    USD
2024-01-01 open Assets:Savings     USD
2024-01-01 open Expenses:Food      USD
2024-01-01 open Equity:Opening-Balances
 
; 3. Initial Balances
; Pad fills the gap up to Equity:Opening-Balances, so it must be dated
; before the assertion. Balance assertions are checked at the start of
; their day, so assert the next morning.
2024-01-01 pad Assets:Checking Equity:Opening-Balances
2024-01-02 balance Assets:Checking 1000.00 USD
 
; 4. Transactions
2024-01-15 * "Grocery Store" "Weekly groceries"
  Expenses:Food            50.00 USD
  Assets:Checking

Section Organization​

1. Eternal Accounts

   2024-01-01 open Liabilities:Payables    USD
   2024-01-01 open Assets:Receivables      USD

2. Bank Accounts

   2024-01-01 open Assets:Bank:Checking     USD
   2024-01-01 open Assets:Bank:Savings      USD
   2024-01-01 open Income:Bank:Interest     USD

3. Investment Accounts

   2024-01-01 open Assets:Investment:Cash    USD
   2024-01-01 open Assets:Investment:Stocks  VTSAX
   2024-01-01 open Income:Investment:Dividend USD

Validation and Reporting​

Basic Validation​

# Check for errors (prints nothing and exits 0 when clean)
bean-check ledger.beancount
 
# Browse balances, reports, and charts in the web interface
fava ledger.beancount

bean-check is the validator: it prints nothing and exits 0 when the ledger is clean, and lists every error and exits non-zero otherwise. Fava is the web interface — run it and open the printed http://localhost:5000 address for the balance sheet, income statement, and account journals.

Common Reports​

Beancount 3 produces reports through Fava's web interface or ad-hoc queries with bean-query, which runs the Beancount Query Language. The older bean-report and bean-web commands were removed in Beancount 3, so the commands below replace them.

# Balance-sheet numbers: balances by asset, liability, and equity account
bean-query ledger.beancount "SELECT account, sum(position) AS balance WHERE account ~ '^(Assets|Liabilities|Equity)' GROUP BY account ORDER BY account"
 
# Income-statement numbers: totals by income and expense account
bean-query ledger.beancount "SELECT account, sum(position) AS total WHERE account ~ '^(Income|Expenses)' GROUP BY account ORDER BY account"
 
# One account's journal, with a running balance
bean-query ledger.beancount "SELECT date, narration, position, balance WHERE account = 'Assets:Checking'"

Managing Initial Balances​

Padding Example​

2024-01-01 open Assets:Checking    USD
2024-01-01 open Equity:Opening-Balances
 
; Pad account to match a known balance
2024-01-01 pad Assets:Checking Equity:Opening-Balances
 
; Assert the known balance the next day: assertions are evaluated at the
; start of their date, and the pad transaction must fall before it
2024-01-02 balance Assets:Checking 1525.00 USD

A balance assertion checks the account at the start of its date, so it must be dated after the pad (or any transaction) it should include. Dating the pad and the balance on the same day leaves the pad unused and the assertion short — Beancount reports Unused Pad entry and Balance failed. The Equity:Opening-Balances account must be opened before it is padded against.

Account Closure​

2024-01-01 open Assets:OldBank:Checking   USD
2024-06-30 close Assets:OldBank:Checking  ; Account closed

Transaction De-duplication​

Handling Transfers​

; Credit card payment - combined view
2024-01-15 * "Credit Card Payment"
  Assets:Checking            -500.00 USD
  Liabilities:CreditCard     500.00 USD
 
; Flag for pending match
2024-01-15 * "Pending CC Payment"
  ! Assets:Checking         -500.00 USD
  Liabilities:CreditCard    500.00 USD

Balance Assertions​

; Regular balance checks prevent duplicates
2024-01-31 balance Assets:Checking    2150.25 USD
2024-01-31 balance Liabilities:CreditCard  -350.00 USD

Best Practices​

1. File Organization

   • Keep one main file initially
   • Use clear section headers
   • Group related accounts together

2. Account Names

   • Use consistent naming conventions
   • Include country/institution prefixes
   • Maintain logical hierarchy

3. Balance Verification

   • Regular balance assertions
   • Pad accounts appropriately
   • Track account closures

4. Currency Handling

   • Declare operating currencies
   • Use consistent commodity codes
   • Specify currency constraints

Next Steps​

Now that you have a basic ledger set up:

1. Record Regular Transactions: Start with your daily expenses and income
2. Set Up Bank Account Imports: Use CSV imports or bank connections to automate data entry. Paste a statement export into the CSV to Beancount converter to get balanced entries in your browser, or use OFX & QIF to Beancount for .ofx, .qfx and .qif downloads.
3. Copy a Proven Layout: Download a runnable starter file from the household, envelope budgeting, or freelance sections of the working ledger examples, then adapt the property and investing patterns from the same gallery
4. Learn Advanced Syntax: Explore syntax reference for more complex scenarios
5. Generate Your First Reports: Use the UI features to create financial reports and analyze your spending

Quick Reference​

Common Account Types:

• Assets:Bank:Checking - Your checking account
• Expenses:Food:Groceries - Grocery spending
• Income:Salary:Company - Employment income
• Liabilities:CreditCard:Visa - Credit card debt

Essential Commands:

• bean-check ledger.beancount - Validate your ledger (exits non-zero on errors)
• fava ledger.beancount - Launch the web interface for reports and charts
• bean-query ledger.beancount "SELECT ..." - Query balances and transactions

These guidelines establish a solid foundation for managing personal finances with Beancount. Ready to add your first transaction? Check out our UI transaction guide.