Beancount v3 Format Specification
Overview
Beancount is a double-entry bookkeeping language designed for plain text accounting. This specification defines version 3 of the Beancount format.
Key Features
- Plain text - Human-readable, version-controllable files
- Double-entry - Enforced balance in every transaction
- Multi-currency - Native support for multiple currencies and commodities
- Cost tracking - Lot-based inventory with multiple booking methods
- Extensible - Metadata, plugins, and custom directives
Quick Example
beancount
; Options
option "title" "Personal Finances"
option "operating_currency" "USD"
; Account structure
2024-01-01 open Assets:Checking USD
2024-01-01 open Assets:Savings USD
2024-01-01 open Expenses:Food
2024-01-01 open Income:Salary
; Transactions
2024-01-15 * "Employer" "Monthly salary"
Assets:Checking 5000.00 USD
Income:Salary
2024-01-16 * "Grocery Store" "Weekly groceries"
Expenses:Food 125.50 USD
Assets:Checking
; Balance assertion
2024-01-17 balance Assets:Checking 4874.50 USDSpecification Structure
Core Specification
| Document | Description |
|---|---|
| spec/introduction.md | Overview and terminology |
| spec/lexical.md | Tokens, encoding, whitespace |
| spec/syntax.md | Grammar and file structure |
Directives
| Directive | Document |
|---|---|
| Transaction | spec/directives/transaction.md |
| Open | spec/directives/open.md |
| Close | spec/directives/close.md |
| Balance | spec/directives/balance.md |
| Pad | spec/directives/pad.md |
| Commodity | spec/directives/commodity.md |
| Price | spec/directives/price.md |
| Event | spec/directives/event.md |
| Note | spec/directives/note.md |
| Document | spec/directives/document.md |
| Query | spec/directives/query.md |
| Custom | spec/directives/custom.md |
| Option | spec/directives/option.md |
| Plugin | spec/directives/plugin.md |
| Include | spec/directives/include.md |
Data Elements
| Element | Document |
|---|---|
| Postings | spec/posting.md |
| Amounts | spec/amounts.md |
| Costs | spec/costs.md |
| Prices | spec/prices.md |
| Metadata | spec/metadata.md |
| Tags & Links | spec/tags-links.md |
Semantics
| Topic | Document |
|---|---|
| Booking Methods | spec/booking.md |
| Tolerances | spec/tolerances.md |
| Include Processing | spec/includes.md |
| Error Codes | spec/errors.md |
Validation
| Topic | Document |
|---|---|
| Account Lifecycle | spec/validation/accounts.md |
| Balance Checking | spec/validation/balance.md |
| Currency Rules | spec/validation/commodities.md |
| Duplicate Detection | spec/validation/duplicates.md |
Grammar
| Format | File | Description |
|---|---|---|
| PEG | grammar/beancount.peg | Parsing Expression Grammar |
| EBNF | grammar/beancount.ebnf | ISO 14977 EBNF |
| ABNF | grammar/beancount.abnf | RFC 5234 ABNF |
Schema
| Format | File | Description |
|---|---|---|
| JSON Schema | schema/ast.schema.json | AST validation |
| Protocol Buffers | schema/ast.proto | Binary serialization |
Editor Support
Tree-sitter
Complete tree-sitter grammar for syntax highlighting and editor integration:
- tree-sitter/grammar.js - Parser grammar
- tree-sitter/queries/highlights.scm - Syntax highlighting
- tree-sitter/queries/folds.scm - Code folding
- tree-sitter/queries/indents.scm - Auto-indentation
Query Language
Beancount includes BQL (Beancount Query Language) for querying ledger data:
- bql/spec.md - BQL specification
- bql/functions.md - Built-in functions
Migration
- migration/guide.md - Migrating from v2 to v3
- migration/breaking-changes.md - Breaking changes list
File Extension
Beancount files use the .beancount extension:
ledger.beancount
accounts.beancount
2024/january.beancountSome tools also recognize .bean as an alternative.
Implementations
| Implementation | Language | Status |
|---|---|---|
| beancount | Python | Reference |
| rustledger | Rust | Compatible |
| beancount-parser | Rust | Parser only |
Resources
License
This specification is licensed under CC-BY-4.0.