# Beancount — Plain-Text Double-Entry Bookkeeping

> A Python-based double-entry bookkeeping system that uses plain-text files as the data source, with a focus on correctness, auditability, and extensibility through plugins.

## Install

Save as a script file and run:

# Beancount — Plain-Text Double-Entry Bookkeeping

## Quick Use
```bash
pip install beancount fava
```
```
; Save as finances.beancount
option "operating_currency" "USD"

2024-01-01 open Assets:Checking
2024-01-01 open Expenses:Food
2024-01-01 open Income:Salary

2024-01-15 * "Employer" "Monthly salary"
  Assets:Checking    5000.00 USD
  Income:Salary

2024-01-20 * "Grocery Store" "Weekly groceries"
  Expenses:Food       120.00 USD
  Assets:Checking
```
```bash
bean-check finances.beancount
fava finances.beancount  # Opens web UI on localhost:5000
```

## Introduction
Beancount is a double-entry bookkeeping system where financial data lives in plain-text files. Written in Python, it emphasizes correctness through strict validation and offers Fava, a companion web interface, for interactive exploration of financial reports.

## What Beancount Does
- Validates and processes plain-text ledger files with strict double-entry enforcement
- Generates income statements, balance sheets, and trial balances from transaction data
- Tracks multiple currencies, commodities, and investment lots with cost basis
- Provides Fava, a web-based dashboard for browsing accounts, charts, and reports
- Supports extensibility through Python plugins for custom validation and transformation

## Architecture Overview
Beancount parses a ledger file into an in-memory stream of directives (transactions, balance assertions, open/close events). A processing pipeline applies plugins that validate, transform, or augment the directive stream. The output is consumed by reporting tools like bean-report or the Fava web server, which renders interactive dashboards using Flask.

## Self-Hosting & Configuration
- Install Beancount and Fava via pip in a Python virtual environment
- Store ledger files in a Git repository for version-controlled audit trails
- Configure operating currency and account hierarchies with option directives
- Write Python plugins to automate recurring entries or enforce custom rules
- Run Fava locally or on a server for shared access to financial dashboards

## Key Features
- Strict validation that catches unbalanced transactions and account errors at parse time
- Fava web interface with interactive charts, account drill-down, and query language
- Python plugin system for custom importers, transformations, and validation rules
- Multi-currency support with automatic cost tracking and unrealized gains reporting
- Deterministic processing: same input always produces the same output

## Comparison with Similar Tools
- **Ledger** — C++ original with faster parsing; Beancount has stricter validation and Fava web UI
- **hledger** — Haskell-based with its own web UI; Beancount offers Python extensibility
- **GnuCash** — GUI desktop app; Beancount is text-first with version control integration
- **Firefly III** — Web-based personal finance; Beancount is developer-oriented with plain-text storage

## FAQ
**Q: What is Fava?**
A: Fava is a web frontend for Beancount that visualizes accounts, balances, and reports in a browser.

**Q: Can I import bank statements?**
A: Yes, Beancount has an importer framework and community tools for converting CSV/OFX to Beancount format.

**Q: Is Beancount suitable for business accounting?**
A: Yes, it handles multi-currency, invoicing workflows, and tax reporting for small businesses.

**Q: How does Beancount differ from Ledger?**
A: Beancount requires accounts to be explicitly opened, enforces stricter balancing rules, and uses Python instead of C++.

## Sources
- https://github.com/beancount/beancount
- https://beancount.github.io

---
Source: https://tokrepo.com/en/workflows/asset-13e62947
Author: Script Depot