Beancount v3 Specification - Introduction
Overview
Beancount is a double-entry bookkeeping language for plain text accounting. It provides a simple, human-readable format for recording financial transactions and a set of tools for processing, validating, and querying the data.
Purpose
This specification defines:
- Syntax - The grammar of Beancount files
- Semantics - The meaning of directives and their behavior
- Validation - Rules for detecting errors
- Processing - How files are loaded and transformed
Design Principles
Plain Text
All data is stored in human-readable text files:
- Version controllable (git, mercurial)
- Grep-able and scriptable
- No proprietary formats
- Long-term archival friendly
Double-Entry Accounting
Every transaction must balance:
- Sum of debits equals sum of credits
- Enforced by the parser/validator
- Prevents common bookkeeping errors
Declarative
Files declare facts, not procedures:
- No imperative control flow
- Order within files doesn't matter (directives are sorted by date)
- Idempotent processing
Extensible
Support for custom data and transformations:
- Metadata on any directive
- Custom directives for arbitrary data
- Plugin system for transformations
Document Structure
Core Specification
| Document | Description |
|---|---|
| lexical.md | Tokens, whitespace, comments, encoding |
| syntax.md | Grammar overview, file structure |
| posting.md | Posting structure within transactions |
| amounts.md | Number and amount formats |
| costs.md | Cost basis specification |
| prices.md | Price annotations |
| metadata.md | Key-value metadata |
| tags-links.md | Tags and links |
Directives
| Directive | Description |
|---|---|
| transaction.md | Financial exchanges |
| open.md | Account declarations |
| close.md | Account closures |
| balance.md | Balance assertions |
| pad.md | Automatic balancing |
| commodity.md | Currency declarations |
| price.md | Market prices |
| event.md | Variable tracking |
| note.md | Account notes |
| document.md | File attachments |
| query.md | Embedded queries |
| custom.md | User-defined directives |
| option.md | Configuration |
| plugin.md | Transformations |
| include.md | File inclusion |
Validation
| Document | Description |
|---|---|
| validation/accounts.md | Account lifecycle |
| validation/balance.md | Balance checking |
| validation/commodities.md | Currency rules |
| validation/duplicates.md | Duplicate detection |
| errors.md | Error codes catalog |
Semantics
| Document | Description |
|---|---|
| booking.md | Lot matching methods |
| tolerances.md | Balance tolerances |
| includes.md | Include semantics |
Terminology
RFC 2119 Keywords
This specification uses RFC 2119 keywords:
| Keyword | Meaning |
|---|---|
| MUST | Absolute requirement |
| MUST NOT | Absolute prohibition |
| SHOULD | Recommended but not required |
| SHOULD NOT | Not recommended but not prohibited |
| MAY | Optional |
Definitions
| Term | Definition |
|---|---|
| Directive | A dated entry in the ledger |
| Transaction | A directive recording a financial exchange |
| Posting | A single line within a transaction |
| Account | A named container for tracking value |
| Commodity | A unit of measurement (currency, stock, etc.) |
| Amount | A number paired with a commodity |
| Cost | The acquisition price of a commodity |
| Price | The market exchange rate |
| Lot | A specific acquisition of a commodity |
| Inventory | The collection of lots in an account |
Version History
| Version | Date | Changes |
|---|---|---|
| v3.0 | 2024 | Current specification |
| v2.0 | 2016 | Python 3, Unicode support |
| v1.0 | 2012 | Initial release |
Conformance
Implementations claiming Beancount compatibility MUST:
- Parse all valid Beancount syntax
- Reject all invalid syntax with appropriate errors
- Implement all required validation rules
- Support the standard booking methods
See conformance/ for the conformance testing program.
Example
A minimal Beancount file:
beancount
; Personal Finance Ledger
option "title" "My Finances"
option "operating_currency" "USD"
; Account definitions
2024-01-01 open Assets:Checking USD
2024-01-01 open Expenses:Food
2024-01-01 open Income:Salary
; Transactions
2024-01-15 * "Employer" "Monthly salary"
Assets:Checking 3000.00 USD
Income:Salary
2024-01-16 * "Grocery Store" "Weekly groceries"
Expenses:Food 85.50 USD
Assets:Checking
; Balance assertion
2024-01-17 balance Assets:Checking 2914.50 USD