当前更新至 2026-09-15。
Beancount 第三版于 2024 年年中发布，标志着这款广受欢迎的纯文本会计工具在架构上的重大演进。虽然它对用户的账本文件保持了向后兼容，但底层结构及配套工具经历了显著变化。以下是 Beancount v3 的新内容以及自本指南首次发布以来在 3.1–3.2 系列中新增的功能。
关于语法和首个账本，请参阅 Beancount 语法参考 和 入门指南。关于封装了检查、查询、导入和报表功能的托管命令行界面，请参阅 Beancount CLI 参考。
更模块化、更精简的架构
Beancount v3 最显著的变化是转向更模块化的生态系统。以前捆绑在核心中的多项关键功能已被拆分到独立项目中。这使得 Beancount 的核心更精简，并且能够对各组件进行更有针对性的开发。
现在拆分为独立包的关键组件包括：
- beanquery：用于账本文件的强大的类 SQL 查询工具，现在位于自己的包中。
- beangulp：这是数据导入框架的新家，取代了以前的
beancount.ingest模块。 - beanprice：用于获取商品和股票价格的专用工具。
这种拆分意味着用户需要在 beancount 之外另行安装这些包，才能保留你在版本 2 中使用过的全部功能。
命令行工具和工作流程的变化
反映新的模块化架构，命令行工具也有一些值得注意的变化：
bean-report已被移除：这个工具已被移除。现在建议你使用bean-query（来自beanquery包）来满足报表需求。- 新的导入器工作流程：
bean-extract和bean-identify命令已从核心中移除。使用beangulp的新方法是基于脚本的。你将创建自己的 Python 脚本来处理从外部来源（如银行对账单）导入数据。
语法和功能增强
虽然核心会计原则保持不变，但 Beancount v3 为语法引入了一些受欢迎的灵活性：
- 更灵活的货币代码：以前对货币名称的长度和字符的限制已放宽。现在支持单字符货币符号。
- 扩展的交易标志：你现在可以使用 A 到 Z 之间的任何大写字母作为交易的标志，从而实现更细粒度的分类。
重要的是，这些变化是向后兼容的，因此你现有的 Beancount v2 账本文件无需任何修改即可继续使用。
C++ 重写与性能
Beancount 的长期目标之一是用 C++ 重写其性能关键组件。Beancount v3 的初始版本没有包含 C++ 核心，截至 2026-09-15 仍然如此：已发布的 PyPI 版本线（至 3.2.3）仍然是模块化的 Python v3 分支。历史上的 C++/Bazel 工作位于单独的 cpp 分支上，不属于用户从 PyPI 安装的包。因此，当前 v3 版本的日常性能与 v2 后期处于同一水平，主要是解析器和工具的渐进式改进，而不是数量级的 C++ 重写。
自本文撰写以来（v3.1 → v3.2.x）
主要来源：项目 CHANGES 文件、GitHub 上 3.1.0…3.2.0 的对比视图，以及 PyPI beancount（截至 2026-09-15 最新版为 3.2.3）。
- 3.1.x 系列 — 在 3.0 模块化拆分（
beanquery、beangulp、beanprice仍为独立安装）后继续开展打包和 API 清理。 - 3.2.0（2025-09-14） —
beancount/beancount上的发布提交；该时间段内面向用户的显著工作包括多文件bean-format、容差/精度改进以及 wheel/CI 维护（请参阅上面的对比链接）。 - 3.2.1–3.2.3（2026） — 后续的二进制和打包发布（包括 3.2.1 摘要中提到的 Python 3.14 测试覆盖和文档脚手架）。使用
pip install -U beancount安装，并在升级时将配套包（beanquery、beangulp）固定到匹配的主版本。
Fava： Fava 1.30 添加了对 Beancount 3 的支持（2024-12-29）。Fava 1.30.13（2026-05-19） 放弃了对 Beancount 2 的支持，并且导入器需要使用 beangulp。截至 2026-09-15，当前的 PyPI 版本为 1.30.16。将 Fava 升级与 Beancount 3 账本配合使用。
从 v2 迁移到 v3
对大多数用户来说，从 Beancount v2 迁移到 v3 相对简单：
- 账本文件：你的
.beancount文件无需任何更改。 - 安装：你需要使用
pip安装新的独立包，如beanquery和beangulp。 - 导入器脚本：如果你有自定义导入器，你需要更新它们以使用新的
beangulpAPI。这主要涉及更改导入器继承的基类并调整一些方法签名。 - Fava：Beancount 广受欢迎的 Web 界面 Fava 已更新以兼容 v3。请确保你拥有最新版本的 Fava，以获得流畅的体验。
本质上，Beancount v3 是一个基础性版本，精简了项目架构，使其更加模块化，从长远来看更易于维护和扩展。虽然它要求你对工作流程进行一些调整，尤其是围绕数据导入，但它为这款强大会计工具的未来发展奠定了基础。
