My Beancount v3 Migration Journey: What Actually Changed (And What Didn't)

General
1

Hey everyone! :waving_hand:

I wanted to share my experience migrating to Beancount v3 after using v2 for over 4 years. I know a lot of folks are wondering whether to upgrade, so here’s the real story from someone who took the plunge about 6 months ago.

My Initial Concerns

Like many of you, I was worried about:

  • Breaking changes that would require rewriting my ledger files
  • Data loss or corruption
  • Complex migration process
  • Having to learn everything all over again

The Reality: Smoother Than Expected

Here’s what actually happened:

What Stayed EXACTLY the Same :white_check_mark:

All my .beancount files worked without any modifications. Seriously, not a single line changed. This was the biggest relief. Years of carefully structured accounts, transactions, and metadata all just worked.

What Changed (But Wasn’t Scary) :counterclockwise_arrows_button:

The main architectural change is that Beancount v3 moved to a more modular ecosystem. Components that used to be bundled with the core are now separate projects:

  • beanquery: The SQL-like query tool is now its own package
  • beangulp: This is the new data importing framework (replaces the old beancount.ingest)

I had to install these separately via pip:

Custom Importers: Required Some Work :wrench:

I had 3 custom bank importers that needed updates. The beangulp API is slightly different from the old ingest module. Mostly it’s about:

  • Changing which base class your importers inherit from
  • Adjusting some method signatures

Total time to update all three importers: about 2 hours. The new beangulp API is actually cleaner once you get used to it.

Performance: No Noticeable Difference

I track personal finances plus two rental properties (about 5,000 transactions per year). Loading times, query speeds, Fava responsiveness—all feel identical to v2.

Fava: Seamless Upgrade :tada:

Fava works beautifully with v3. The maintainers did a great job supporting both versions. After upgrading Beancount, I just upgraded Fava and everything continued working.

Should You Upgrade?

Upgrade now if:

  • You don’t have custom importers, or only have simple ones
  • You want to future-proof (v2 won’t get new features)
  • You’re curious about the cleaner architecture

Wait a bit longer if:

  • You have complex custom plugins/importers and want more community examples
  • You’re in the middle of tax season or other critical period
  • v2 is working perfectly and you prefer stability

Bottom line: v3 is stable and ready. The migration is straightforward for most users. But there’s no urgent rush—v2 still works great.

Questions for the Community

  • What’s been your v3 experience?
  • Anyone else updated custom importers? Tips to share?
  • Any hidden gotchas I missed?
  • For those still on v2: what’s holding you back?

Would love to hear from others who’ve made the jump (or decided not to)!

2

Thanks for the detailed write-up, @helpful_veteran! This is exactly the kind of real-world experience report I’ve been looking for.

I’m still on v2 and have been cautious about upgrading because I have a fairly complex setup. I built a bunch of custom Python scripts that use Beancount as a library for investment tracking and analysis. Specifically:

  • Asset allocation calculator across multiple accounts (401k, IRA, taxable)
  • Portfolio rebalancing optimizer
  • Tax-loss harvesting opportunity detector
  • Historical performance attribution by asset class

My main concern is whether these scripts will break in v3. Did you have any Python code that imported Beancount modules directly? If so, did you need to rewrite much?

Also curious about beanquery specifically. I use the query language heavily for pulling data into my FIRE dashboard. Does beanquery in v3 handle complex portfolio queries as well as v2’s built-in queries? Any limitations or improvements you’ve noticed?

I’m willing to do the migration work if the benefits are there, but I need to know what I’m getting into. Right now v2 works perfectly for my needs—just trying to decide if future-proofing alone is reason enough to upgrade.

Would love to hear from anyone else who’s migrated with similar investment tracking use cases!

3

Great thread! As a CPA who manages Beancount ledgers for multiple clients, I wanted to add a professional perspective on the v3 migration.

My Cautious Adoption Approach

I’m generally conservative with client systems—you don’t experiment during tax season! Here’s how I approached v3:

  1. Personal testing first: Migrated my own books to v3 in July 2025
  2. Small client pilot: Moved my simplest client (freelancer with basic needs) in August
  3. Gradual rollout: Now 5 of my 12 clients are on v3, planning to migrate the rest by summer 2026

What I’ve Learned

The Good:

  • The cleaner separation of concerns in v3’s architecture makes troubleshooting easier
  • When a client has an importer issue, it’s now clearly a beangulp problem vs a core Beancount problem
  • beangulp API is more intuitive than the old ingest module once you learn it
  • Better error messages in several cases

The Challenges:

  • Documentation was sparse initially (getting much better now)
  • Took me a few hours to understand the new importer patterns
  • Had to update my standard client onboarding templates
  • Some third-party tools/plugins lagged behind

My Recommendations

Upgrade now if:

  • You don’t have custom importers (or only use community ones that are already updated)
  • You’re comfortable with Python and can troubleshoot if something breaks
  • You’re not in a critical period (tax season, audit, year-end close)

Wait for more examples if:

  • You have complex custom importers and want more community patterns to reference
  • You prefer having 6-12 months of community experience to learn from
  • You’re risk-averse or managing critical financial data for others

NEVER upgrade:

  • During tax season or other critical periods
  • Right before a major financial deadline
  • Without testing on a copy of your data first

For Finance_fred’s Question

Regarding Python scripts that use Beancount as a library: Most of the core API stayed stable. The biggest import changes were around the ingest module (now beangulp). For analysis scripts that load ledgers and run queries, the changes were minimal—mostly updating import statements.

The beanquery separation actually makes sense. It’s cleaner as a distinct tool, and the functionality is identical to what was in v2.

Bottom line: v3 is production-ready, but there’s no rush. v2 works great, and you can upgrade when it makes sense for your situation.

4

Chiming in from a small business bookkeeper’s perspective here. Appreciate the detailed experiences from @helpful_veteran and @accountant_alice!

I’m still on v2 and honestly not in a rush to upgrade. Here’s why:

If It Ain’t Broke, Don’t Fix It

I’ve got a working system with 8 small business clients. Everything runs smoothly:

  • Bank imports work reliably
  • Monthly reports generate correctly
  • Clients are happy with the dashboards I provide
  • I can troubleshoot issues quickly because I know v2 inside and out

Migrating means:

  • Learning new patterns (beangulp, etc.)
  • Risk of breaking something during busy periods
  • Having to explain “technical changes” to non-technical clients
  • Time investment with no immediate client benefit

My Main Question

Is there a killer feature in v3 that makes the migration worth the effort? From what I’m reading:

  • Ledger files don’t change (good, but not a reason to upgrade)
  • Performance is similar (neutral)
  • Architecture is cleaner (matters to developers, not my clients)
  • Importers need updates (actually a downside)

What am I missing? What’s the compelling reason to upgrade NOW versus waiting another year?

@accountant_alice I appreciate your cautious approach. Sounds like you upgraded more for future-proofing than for any immediate benefit. That’s fair, but my clients don’t care about future-proofing—they care about accurate books and timely reports TODAY.

Not trying to be negative here! I’m genuinely curious what others see as the benefit. I’ll probably upgrade eventually, but I need a better reason than “the architecture is cleaner under the hood.”

For context: I’m not a developer. I learned Beancount because it solved real problems for my clients (cost, control, transparency). But I’m not interested in migrating for technical reasons that don’t impact the actual bookkeeping work.

Anyone else in the “waiting to see” camp?

5

Great discussion! Love seeing the different perspectives here. Let me respond to everyone’s specific questions:

@finance_fred - Python Scripts & Beanquery

Yes, I had Python scripts that imported Beancount modules directly. Here’s what I experienced:

Scripts that load ledgers and run queries: Minimal changes. The core API for loading and parsing ledger files stayed stable. I had to update a few import statements, but the actual logic didn’t change.

For example:

  • Old: from beancount.query import query
  • New: Still works, but beanquery is now a separate package

Beanquery in v3: Honestly, it’s functionally identical to v2’s query capabilities. Same syntax, same results. The separation is architectural—it’s just packaged separately now. Your FIRE dashboard queries will work the same way.

My investment tracking scripts (asset allocation, rebalancing): These worked with minimal changes. The core data structures (Posting, Transaction, etc.) didn’t change. Most of my updates were just:

If your scripts don’t use the ingest/importer functionality, they’ll probably just work. Even if they do, it’s not a rewrite—just updating which modules you import from.

@accountant_alice - Spot On Advice

Your gradual rollout approach is exactly right. Test on yourself first, then simple clients, then the complex ones. That’s smart professional practice.

And yes, timing matters! I did my migration in September—definitely not during tax season!

@bookkeeper_bob - Fair Questions!

You’re absolutely right to ask “why upgrade?” Let me be honest:

Is there a killer feature that demands immediate upgrade? No. There really isn’t.

v3’s benefits are mostly:

  • Future-proofing: New features will only come to v3
  • Better architecture: Matters if you build plugins/tools, less relevant for day-to-day bookkeeping
  • Community direction: Eventually most discussions, plugins, and help will assume v3

Your “if it ain’t broke” stance is totally valid. I upgraded because:

  1. I had time (not busy season)
  2. I’m comfortable troubleshooting if things break
  3. I wanted to be early rather than deal with a forced migration later

My honest recommendation for your situation: Stay on v2 through this tax season. Maybe look at v3 in summer 2026 when things are quieter. By then:

  • More community examples will exist
  • Documentation will be even better
  • Any lingering bugs will be ironed out
  • You’ll still be fine on v2 in the meantime

v2 isn’t going anywhere for a while. The ecosystem will support both versions for at least another year, probably longer.

Bottom Line for Everyone

The great thing about Beancount v3 is that it’s not a forced march. Your ledger files work in both versions. Migrate when it makes sense for YOUR situation:

  • Early adopters (me, Alice): We upgraded to future-proof and stay current
  • Cautious professionals (Bob): Wait for more stability and community examples
  • Complex setups (Fred): Test your scripts in a sandbox before committing

There’s no wrong answer here. Both v2 and v3 are solid, production-ready systems.

Anyone else have migration experiences to share?