# Beancount v3: What's New?

Current as of 2026-09-15.

Beancount version 3, released in mid-2024, marks a significant architectural evolution for the popular plain-text accounting tool. While it maintains backward compatibility for user ledger files, the underlying structure and accompanying tools have undergone substantial changes. Here’s a breakdown of what’s new in Beancount v3 — and what has landed in the 3.1–3.2 line since this guide was first published.

For syntax and first ledgers, see the [Beancount syntax reference](/docs/Basics/syntax) and [Getting started](/docs/Basics/getting-started). For the hosted CLI that wraps check, query, import, and reports, see the [Beancount CLI reference](/docs/bea-cli-reference).

## **A More Modular and Streamlined Architecture**

The most significant change in Beancount v3 is the move to a more modular ecosystem. Several key functionalities that were previously bundled with the core have been spun off into separate, independent projects. This makes the core of Beancount leaner and allows for more focused development on individual components.

The key components that are now separate packages include:

- **beanquery**: The powerful SQL-like query tool for your ledger files is now in its own package.
- **beangulp**: This is the new home for the data importing framework, replacing the former `beancount.ingest` module.
- **beanprice**: A dedicated tool for fetching prices of commodities and stocks.

This separation means that users will need to install these packages in addition to `beancount` itself to retain the full functionality they were used to in version 2.

## **Changes to Command-Line Tools and Workflows**

Reflecting the new modular architecture, there are some notable changes to the command-line tools:

- **`bean-report` is gone**: This tool has been removed. Users are now encouraged to use `bean-query` (from the `beanquery` package) for their reporting needs.
- **New Importer Workflow**: The `bean-extract` and `bean-identify` commands have been removed from the core. The new approach with `beangulp` is script-based. Users will now create their own Python scripts to handle the importing of data from external sources like bank statements.

## **Syntax and Feature Enhancements**

While the core accounting principles remain the same, Beancount v3 introduces some welcome flexibility to its syntax:

- **More Flexible Currency Codes**: The previous restrictions on the length and characters for currency names have been relaxed. Single-character currency symbols are now supported.
- **Expanded Transaction Flags**: Users can now use any capital letter from A to Z as a flag for transactions, allowing for more granular categorization.

Importantly, these changes are backward-compatible, so your existing Beancount v2 ledger files will work without any modifications.

## **The C++ Rewrite and Performance**

One of the long-term goals for Beancount has been a rewrite of its performance-critical components in C++. The initial release of Beancount v3 did **not** include a C++ core, and as of 2026-09-15 that remains true: the published PyPI line (through **3.2.3**) is still the modular Python v3 branch. The historical C++/Bazel work lives on a separate `cpp` branch and is not part of the packages users install from [PyPI](https://pypi.org/project/beancount/). Day-to-day performance of current v3 releases is therefore in the same class as late v2, with incremental parser and tooling improvements rather than an order-of-magnitude C++ rewrite.

## **Since this was written (v3.1 → v3.2.x)**

Primary sources: the project [CHANGES](https://github.com/beancount/beancount/blob/master/CHANGES) file, GitHub compare views for [3.1.0…3.2.0](https://github.com/beancount/beancount/compare/3.1.0...3.2.0), and [PyPI beancount](https://pypi.org/project/beancount/) (latest **3.2.3** as of 2026-09-15).

- **3.1.x line** — Continued packaging and API cleanup after the 3.0 modular split (`beanquery`, `beangulp`, `beanprice` remain separate installs).
- **3.2.0 (2025-09-14)** — Release commit on `beancount/beancount`; notable user-facing work in the window includes multi-file `bean-format`, tolerance/precision refinements, and wheel/CI maintenance (see the compare link above).
- **3.2.1–3.2.3 (2026)** — Follow-on binary and packaging releases (including Python 3.14 test coverage and docs scaffolding called out in the 3.2.1 summary on the mailing list). Install with `pip install -U beancount` and pin companions (`beanquery`, `beangulp`) to matching majors when upgrading.

**Fava:** [Fava 1.30](https://beancount.github.io/fava/changelog.html) added Beancount 3 support (2024-12-29). **Fava 1.30.13 (2026-05-19)** dropped Beancount 2 support and expects **beangulp** for importers. Current PyPI line as of 2026-09-15 is **1.30.16**. Pair Fava upgrades with a Beancount 3 ledger.

## **Migrating from v2 to v3**

For most users, the migration from Beancount v2 to v3 is relatively straightforward:

1. **Ledger Files**: No changes are needed for your `.beancount` files.
2. **Installation**: You will need to install the new, separate packages like `beanquery` and `beangulp` using `pip`.
3. **Importer Scripts**: If you have custom importers, you will need to update them to use the new `beangulp` API. This mainly involves changing the base class your importers inherit from and adjusting some method signatures.
4. **Fava**: The popular web interface for Beancount, Fava, has been updated to be compatible with v3. Ensure you have the latest version of Fava for a seamless experience.

In essence, Beancount v3 is a foundational release that streamlines the project's architecture, making it more modular and easier to maintain and extend in the long run. While it requires some adjustments to user workflows, especially around data importing, it sets the stage for the future development of this powerful accounting tool.

## Further reading

- [Getting started with Beancount](/docs/Basics/getting-started)
- [Beancount syntax reference](/docs/Basics/syntax)
- [Beancount CLI reference (`bea`)](/docs/bea-cli-reference)
- [Community setups, plugins, and workflows](/docs/community-showcase)
