Migrating from Python Beancount

rustledger is designed as a drop-in replacement for Python beancount with 10-30x better performance.

Quick Start

Your existing beancount files work as-is:

# Validate with rustledger
rledger check ledger.beancount

# Run queries
rledger query ledger.beancount "SELECT account, sum(position) GROUP BY account"

Compatibility

Fully Compatible

• All beancount syntax
• All directive types (transaction, balance, open, close, etc.)
• All booking methods (FIFO, LIFO, STRICT, etc.)
• BQL query language
• Include directives
• Options
• Metadata

Plugin Compatibility

Plugin	Status	Notes
auto_accounts	✅ Native	Faster implementation
implicit_prices	✅ Native	Faster implementation
check_commodity	✅ Native
coherent_cost	✅ Native
leafonly	✅ Native
noduplicates	✅ Native
onecommodity	✅ Native
sellgains	✅ Native
unique_prices	✅ Native
Custom Python plugins	⚠️ WASM	Requires compilation

See Plugins Reference for full list.

Known Differences

1. Decimal precision: rustledger uses 28-digit precision vs Python's arbitrary precision. This only affects extreme edge cases (28+ decimal places).

2. Error messages: Format differs but contains same information.

3. Plugin loading: Python plugins require WASM compilation.

Migration Steps

1. Install rustledger

cargo install rustledger

2. Validate Your Ledger

rledger check ledger.beancount

Compare output with Python beancount:

bean-check ledger.beancount

3. Test Reports

# Balance report
rledger report balances ledger.beancount

# Compare with
bean-report ledger.beancount balances

4. Test Queries

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

5. Update Your Workflow

Replace beancount commands:

Python Beancount	rustledger
bean-check	rledger check
bean-query	rledger query
bean-report	rledger report
bean-format	rledger format
bean-price	rledger price
bean-extract	rledger extract

6. Update Editor

If using VS Code or other editors with Python beancount LSP, switch to rustledger LSP for better performance.

Plugin Migration

Python Plugins to WASM

For custom Python plugins, you have options:

1. Rewrite in Rust: Add to rustledger-plugin/src/native/
2. Compile to WASM: Use py2wasm (experimental)
3. Use pre/post hooks: For simple transformations

Check Plugin Equivalents

Many Python plugins have native Rust equivalents:

; Before (Python)
plugin "beancount.plugins.auto_accounts"

; After (rustledger) - same syntax, native implementation
plugin "beancount.plugins.auto_accounts"

Performance Comparison

Typical speedups on real ledgers:

Ledger Size	Python	rustledger	Speedup
1,000 txns	2.5s	0.1s	25x
10,000 txns	8s	0.3s	27x
50,000 txns	35s	1.2s	29x

Troubleshooting

"Unknown plugin" Error

The plugin may not be implemented yet. Check Plugins Reference or open an issue.

Different Balance

Check for precision differences:

# Python
bean-query ledger.beancount "SELECT sum(position) WHERE account ~ 'Assets'"

# rustledger
rledger query ledger.beancount "SELECT sum(position) WHERE account ~ 'Assets'"

If amounts differ by tiny fractions (e.g., 1e-20), it's a precision difference and can be ignored.

Query Syntax Differences

BQL is compatible, but check:

• Date literals: Use 2024-01-15 not "2024-01-15"
• Regex: Use account ~ "pattern" for regex matching

See Also

• Installation - Install rustledger
• Commands - Command reference
• Plugins - Plugin compatibility