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 also use bean-check, bean-query, etc.

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

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: