# Beancount tutorial: install and first ledger

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.

![beancount.io journal view listing plain-text double-entry transactions with directive type filters](/img/ledger/journal-example.webp)

*[Explore the live ledger →](https://beancount.io/ledger/open_ledger/example/journal)*


## Initial Setup

### Creating Your First Ledger

```bean
; 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

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

## File Organization

### Recommended Structure

```bean
; 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**

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

2. **Bank Accounts**

   ```bean
   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**

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

```bash
# Check for errors (exits 0 when clean)
bea --file ledger.beancount check

# Browse balances, reports, and charts in the web interface
fava ledger.beancount
```

`bea check` is the validator: it exits `0` when the ledger is clean, and lists every error and exits non-zero otherwise. Install it with the [CLI quick start](https://beancount.io/docs/Basics/bea-cli). [Fava](/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, the one-command `bea report`, or ad-hoc queries with `bea query`, which runs the [Beancount Query Language](https://beancount.io/docs/Basics/beancount-query-language). Beancount 3 removed its older report and web commands; `bea report` and Fava replace them.

```bash
# Balance sheet, in one command
bea --file ledger.beancount report balance-sheet

# Income statement, in one command
bea --file ledger.beancount report income-statement

# Balance-sheet numbers: balances by asset, liability, and equity account
bea --file ledger.beancount query "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
bea --file ledger.beancount query "SELECT account, sum(position) AS total WHERE account ~ '^(Income|Expenses)' GROUP BY account ORDER BY account"

# One account's journal, with a running balance
bea --file ledger.beancount query "SELECT date, narration, position, balance WHERE account = 'Assets:Checking'"
```

## Managing Initial Balances

### Padding Example

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

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

## Transaction De-duplication

### Handling Transfers

```bean
; 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

```bean
; 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](/tools/csv-to-beancount) to get balanced entries in your browser, or use [OFX & QIF to Beancount](/tools/ofx-to-beancount) for `.ofx`, `.qfx` and `.qif` downloads.
3. **Copy a Proven Layout**: Download a runnable starter file from the [household](https://beancount.io/docs/examples#everyday-personal-finance), [envelope budgeting](https://beancount.io/docs/examples#envelope-budgeting-that-rolls-over), or [freelance](https://beancount.io/docs/examples#freelancer-invoicing-and-receivables) sections of the [working ledger examples](https://beancount.io/docs/examples), then adapt the property and investing patterns from the same gallery
4. **Learn Advanced Syntax**: Explore [syntax reference](https://beancount.io/docs/Basics/syntax) for more complex scenarios
5. **Generate Your First Reports**: Use the UI features to create financial reports and analyze your spending
6. **Work from the Terminal**: Install the `bea` command line with the [CLI quick start](https://beancount.io/docs/Basics/bea-cli), then close a full month end to end in [Your first month with bea](https://beancount.io/docs/Basics/bea-first-month)

## 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:**

- `bea --file ledger.beancount check` - Validate your ledger (exits non-zero on errors)
- `bea --file ledger.beancount report balance-sheet` - Print a balance sheet
- `bea --file ledger.beancount query "SELECT ..."` - Query balances and transactions
- `fava ledger.beancount` - Launch the web interface for reports and charts

These guidelines establish a solid foundation for managing personal finances with Beancount. Ready to add your first transaction? Check out our [UI transaction guide](https://beancount.io/docs/add-your-first-transaction-ui).
