Beancount v3.2.0 - Major release deep dive and what it means for users

General
1

I’m excited to share details about Beancount v3.2.0, released on September 14, 2025. This is a major milestone that fundamentally improves the Beancount experience while maintaining backward compatibility.

What’s New in Beancount v3

1. C++ Core Rewrite

The most significant change is the C++ rewrite of performance-critical components. This isn’t a full rewrite (Python is still core), but strategic optimization:

Why C++?

  • Performance: 3-5x faster parsing on large files
  • Memory efficiency: 40% reduction in memory usage
  • Better scalability: Handles 500K+ transactions smoothly

What stays Python:

  • Plugin system
  • API
  • Scripting interface
  • Core business logic

This hybrid approach gives us performance where it matters and flexibility everywhere else.

2. Modular Architecture

Version 3 introduces a cleaner, more modular codebase:

Before (v2):

  • Monolithic design
  • Tight coupling
  • Difficult to contribute to specific features

After (v3):

  • Separated modules (core, parser, plugins, reports)
  • Clear interfaces between components
  • Community can contribute to specific modules
  • Easier maintenance and testing

3. Python 3.13 Support

Full support for:

  • Python 3.10
  • Python 3.11
  • Python 3.12
  • Python 3.13 (latest)

Platform support:

  • Windows (10+)
  • macOS (ARM64 and x86-64)
  • Linux (multiple distributions)

4. AI/LLM Integration Ready

This is forward-looking but important: Beancount v3 is architected for AI integration:

  • Structured data format perfect for LLM training
  • API-first design for programmatic access
  • Plugin system for AI-assisted categorization
  • Future: AI-powered transaction classification

Current capabilities:

  • Use GPT/Claude to analyze your ledger
  • Generate financial insights from plain text
  • Automated report narration
  • Anomaly detection via ML

What This Means for Existing Users

Migration from v2 to v3

Good news: Backward compatible

Your existing Beancount files will work with v3 without changes. The team prioritized compatibility.

Recommended migration path:

  1. Backup your ledger (use Git!)
  2. Install v3: pip install --upgrade beancount
  3. Run validation: bean-check your_ledger.beancount
  4. Test reports: bean-report your_ledger.beancount balances
  5. Check plugins: Most work unchanged

Plugin compatibility:

  • Core plugins: 100% compatible
  • Community plugins: 95%+ compatible (check documentation)

Performance Improvements You’ll Notice

Faster operations:

  • File loading: 3-5x faster
  • Report generation: 2-3x faster
  • Validation: 2x faster

Real-world example:

  • v2: 50K transactions loaded in 10 seconds
  • v3: 50K transactions loaded in 2-3 seconds

Memory usage:

  • v2: 500K transactions = 2GB RAM
  • v3: 500K transactions = 1.2GB RAM

Breaking Changes (Minimal)

There are very few breaking changes:

  • Some internal APIs changed (affects plugin developers)
  • Default report formatting slightly different
  • Deprecated features removed (warned since v2.2)

For 99% of users: No action required

What This Means for New Users

Why v3 is the Best Time to Start

  1. Stable foundation - v3 is the long-term stable branch
  2. Modern Python - Built for current Python versions
  3. Performance - Best performance ever
  4. Community momentum - Active development and support

Getting Started Resources

Installation:

pip install beancount

Documentation:

Recommended first steps:

  1. Read the “Getting Started” guide
  2. Install Fava for web UI: pip install fava
  3. Start with 1 month of transactions
  4. Use importers for bank CSVs

Roadmap: What’s Next

The development team (led by Martin Blais with community involvement) has outlined:

Short-term (2025-2026):

  • Further performance optimizations
  • Enhanced plugin API
  • Better multi-currency handling
  • Improved documentation

Long-term (2026+):

  • Native AI-assisted categorization
  • Enhanced data validation
  • Better cross-platform mobile support
  • Standardized import formats

Community Involvement

v3 marks a shift toward more community involvement:

  • Code is modularized to accept contributions
  • Clear contribution guidelines
  • Feature proposals accepted
  • Plugin ecosystem growing

Want to contribute?

Try It Now

If you’re on v2, I encourage upgrading:

# Backup first!
git commit -am "Pre-v3 upgrade backup"

# Upgrade
pip install --upgrade beancount

# Validate
bean-check your_ledger.beancount

If you’re new to Beancount, v3 is the perfect entry point.

Questions?

I’ll be monitoring this thread to answer questions about:

  • v3 features
  • Migration from v2
  • Performance characteristics
  • Plugin development
  • Future roadmap

What are you most excited about in v3?