rustledger

A blazing-fast Rust implementation of Beancount

Parse and validate your ledger faster than Python beancount.

Why rustledger?

When to use rustledger:

• You use Beancount syntax and want speed
• You want a single binary with no runtime dependencies
• You need LSP editor integration
• You want to use existing Python plugins

When to use Python beancount:

• You need Fava web interface (until rustledger integration)
• You have complex Python plugins with C extensions

When to use hledger:

• You prefer hledger's syntax and reports
• You need time-tracking features

Install

_{Missing your platform? Open an issue to request it.}

Coming from Python beancount? See the Migration Guide for command equivalents and plugin mapping.

Quick Start

rledger check ledger.beancount
rledger query ledger.beancount "SELECT account, SUM(position) GROUP BY account"

CLI Commands

Python beancount users can install bean-check, bean-query, etc. wrapper scripts via rledger compat install.

Debugging and diagnostic tools:

# Debug a parsing issue at line 42
rledger doctor context ledger.beancount 42

# Find all transactions with a link
rledger doctor linked ledger.beancount ^trip-2024

# Generate Open directives for accounts missing them
rledger doctor missing-open ledger.beancount >> ledger.beancount

_{Run rledger <command> --help for all options.}

# Validate with plugins
rledger check --native-plugin auto_accounts ledger.beancount

# Interactive query shell
rledger query ledger.beancount

# One-shot query
rledger query ledger.beancount "SELECT date, narration WHERE account ~ 'Expenses:Food'"

# Reports
rledger report ledger.beancount balances
rledger report ledger.beancount stats

# Format in place
rledger format --in-place ledger.beancount

Import & Categorization

rustledger includes a complete bank import pipeline (rledger extract) with automatic CSV/OFX parsing, duplicate detection, transaction categorization, and balance reconciliation.

CSV Import with Auto-Detection

# Auto-detect delimiter, date format, and column roles
rledger extract bank-statement.csv --auto -a Assets:Bank:Checking

# Check against existing ledger to avoid duplicates
rledger extract statement.csv --auto -a Assets:Bank --existing ledger.beancount

# Append balance assertion from bank statement
rledger extract statement.csv --auto -a Assets:Bank --balance 5000.00

# List available importers from config
rledger extract --list-importers --config importers.toml

Importers Configuration

Create importers.toml for reusable import profiles:

[[importers]]
name = "chase"
account = "Assets:Bank:Chase"
date_column = "Transaction Date"
amount_column = "Amount"
date_format = "%m/%d/%Y"

[importers.mappings]
"AMAZON" = "Expenses:Shopping"
"WHOLE FOODS" = "Expenses:Groceries"

rledger extract --importer chase chase-statement.csv

Config is searched in: current directory, ~/.config/rledger/importers.toml, or via --config.

Transaction Categorization

A 3-tier pipeline automatically categorizes transactions:

1. Rules engine — substring, regex, and exact match patterns from importers.toml
2. Merchant dictionary — ~80 built-in patterns across 10 categories (grocery, dining, transport, subscriptions, etc.)
3. ML categorization — TF-IDF + Naive Bayes classification via linfa

Transfer Detection

Automatically identifies inter-account transfers by matching opposite-sign amounts within date windows, with keyword boosting for common transfer indicators.

Duplicate Detection

Fuzzy matching on date + amount + payee/narration prevents importing the same transaction twice. Structural fingerprinting (BLAKE3) provides stable hashes for comparison.

Balance Reconciliation

The --balance flag appends a balance assertion directive matching your bank statement's ending balance, helping verify import accuracy.

Crates

Additionally, document_discovery auto-discovers documents from option "documents" directories.

Python plugins: Run existing Python beancount plugins via CPython-WASI sandbox.

rustledger supports three types of plugins:

Native plugins (built-in, fastest):

# Run a native plugin from CLI
rledger check --native-plugin implicit_prices ledger.beancount

# Or declare in your beancount file (auto-detected as native):
# plugin "beancount.plugins.auto_accounts"

Python file plugins (via WASM sandbox):

# Declare in your beancount file:
# plugin "/path/to/my_plugin.py"

WASM plugins (sandboxed WebAssembly):

# Load a WASM plugin
rledger check --plugin /path/to/plugin.wasm ledger.beancount

How Python plugins work:

• File-based plugins (.py files) run in a sandboxed CPython compiled to WebAssembly
• No system Python installation required
• Plugins cannot access the filesystem or network (sandbox isolation)
• Compatible with most pure-Python beancount plugins

Limitations:

• Module-based plugins (beancount.plugins.xyz) only work if rustledger has a native implementation
• Plugins with C extensions won't work (numpy, pandas, etc.)
• No network access (price fetching plugins need alternatives)

Editor Integration

rustledger includes a full-featured Language Server (rledger-lsp) for IDE support:

• Real-time diagnostics
• Autocompletion (accounts, currencies, payees)
• Go to definition / find references
• Hover information with account balances
• Rename refactoring
• Document formatting

See LSP setup guide for VS Code, Neovim, Helix, Zed, and Emacs.

Performance

_{Benchmarks run nightly on 10K transaction ledgers. View workflow →}

What's measured:

• Validation: Parse ledger + validate (balance assertions, account opens, etc.)
• Balance Report: Parse + compute all account balances

Memory efficiency: rustledger typically uses 3-5x less memory than Python beancount thanks to Rust's zero-cost abstractions and efficient data structures.

Run locally:

# Quick comparison (requires nix)
nix develop .#bench
./scripts/bench.sh

# Criterion micro-benchmarks
cargo bench -p rustledger-core
cargo bench -p rustledger-parser

See BENCHMARKING.md for detailed benchmark documentation.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Documentation:

• Architecture - Crate structure and data flow
• BQL Reference - Query language guide
• Importing - CSV/OFX bank import tutorial
• Validation errors - Error code reference
• API docs - Rust API documentation

By submitting a pull request, you agree to the Contributor License Agreement.

License

GPL-3.0

Commercial licensing available - contact us for proprietary license options.

Funding

rustledger is free and open source. If you find it useful, consider supporting development: