安装 Beancount 

Martin Blais - 更新于 2024 年 11 月

在您的计算机上下载和安装 Beancount 的说明。

发布版本 

Beancount 是一个成熟的项目：首个版本写于 2008 年。当前版本 Beancount —— 分支 "v3" —— 稳定且持续维护和开发中。我们提供邮件列表和PyPI 页面。"master" 分支是开发分支。

(注意：如果您过去使用过 "v2" 分支，许多工具已从 "v3" 分支移除，并迁移至 http://github.com/beancount 下的独立 GitHub 项目。部分工具，例如 bean-report、bean-web，已被弃用。)

获取方式 

这是源代码的官方位置：

https://github.com/beancount/beancount

通过 Git 在您的机器上克隆来下载：

git clone https://github.com/beancount/beancount

安装方法 

安装 Python 

Beancount 使用 Python 3.8 或更高版本（截至本文撰写时已是较新版本），并依赖若干常用库。我尽量减少依赖项，但仍需安装几个。这非常简单。

首先，您应已安装可用的 Python。请从 python.org 下载并安装最新稳定版（≥3.8）。请确保已安装开发头文件和库（例如 "Python.h" 头文件）。例如，在 Debian/Ubuntu 系统上，您需要安装 python3-dev 包。

自 2016 年 2 月起，Beancount 支持 setuptools，您需要安装其依赖项。您应已安装 "pip3" 工具。目前它默认随 Python3 一起安装——请通过运行命令 "python3 -m pip --help" 来测试。

安装 Beancount 

使用 pipx 安装 Beancount 

如果您尚未安装，请先安装 pipx。

接着，使用 pipx 安装 Beancount。这将自动在虚拟环境中下载并安装所有依赖项。

pipx install beancount

确认 Beancount 已安装。

pipx list

在 3.1.0 版本中，这将安装

bean-check
bean-doctor
bean-example
bean-format
treeify

(教程中提到的 bean-report 已被弃用。)

使用 pip 安装 Beancount 

不再推荐使用 pip 安装 Beancount，但您仍可通过以下方式安装 Beancount：

sudo -H python3 -m pip install beancount

这将自动下载并安装所有依赖项。

请注意，这将安装发布到 PyPI 仓库的最新版本，而非从源码获取的最新版本。PyPI 的发布虽不频繁，但通常不会落后太多。

警告：请谨慎操作，此操作可能破坏系统库。

从仓库使用 pip 安装 Beancount 

您也可以直接从其源码仓库使用 pip 安装 Beancount：

sudo -H python3 -m pip install git+https://github.com/beancount/beancount#egg=beancount

从源码安装 Beancount 

从源码安装的优势在于您可以获得稳定分支（“master”）的最新版本。大多数情况下，master 分支的稳定性与发布版本相当。

从官方仓库获取源代码：

git clone https://github.com/beancount/beancount

您可能需要安装一些非 Python 的库依赖项，例如 bison 和 flex，以及其他一些工具（在尝试构建时会发现缺失的依赖）。缺失的内容通常会很明显。如果使用 Ubuntu，请使用 apt-get 安装这些依赖。

如果在 Windows 上安装，请参阅下面的 Windows 部分。

使用 pip3 从源码构建并安装 Beancount 

然后您可以使用 pip 安装所有依赖项和 Beancount 本身：

sudo -H python3 -m pip install .

为开发安装 

如果您希望直接在源码位置执行以进行修改，可以使用 setuptools 的 “develop” 命令指向源码路径：

sudo python3 setup.py develop

警告：这会修改您 Python 安装中的一个 .pth 文件，使其指向您的克隆路径。您可能需要也可能不需要这样做。我本人不采用这种方式；我的做法是本地编译，并设置 shell 环境变量以定位其库文件。您可以这样操作：

make build

您需要先安装 "meson" 和 "ninja"。同时，需要更新 PATH 和 PYTHONPATH 环境变量，以便本地识别导入和二进制文件，如下所示：

export PATH=$PATH:/path/to/beancount/bin
export PYTHONPATH=$PYTHONPATH:/path/to/beancount

开发所需依赖项 

Beancount 开发需要一些额外工具。如果您正在阅读本节，说明您是开发者，因此我假设您知道如何安装包，此处仅列出所需工具：

pytest：用于单元测试
meson、meson-python、ninja：用于构建（在 master 分支上）
ruff：用于代码检查
GNU flex：如果您打算修改词法分析器，则需要此工具。它会生成 C 代码，将输入文件切分为解析器使用的标记。
GNU bison：如果您打算修改语法规则，则需要此传统解析器生成器。它会生成由 flex 输出的标记的解析 C 代码。（我喜欢使用这类旧工具，因为它们依赖极少，仅需 C 代码，几乎可在任何系统上运行。）
python-dateutil：用于运行 beancount.scripts.example 示例生成脚本。

从发行包安装 

各种发行版可能已打包 Beancount。以下是已知存在的相关链接：

Arch： https://aur.archlinux.org/packages/beancount/

Windows 安装 

beancount v3 

如果您打算使用 beancount v3，则无需单独安装它，因为自定义报表和 bean-web 在 v3 中已被弃用，建议直接安装 beanquery。

在这种情况下，安装 beancount 最简单的方法是安装 beanquery，它会自动将 beancount 作为依赖项一并安装。

只需运行以下命令即可：

pip install beanquery

或

python -m pip install beanquery

或者，如果您更喜欢使用 uv，

uv tool install beanquery

要测试安装，请创建一个简单的 Beancount 账本文件：

例如：

====================================

2024-01-01 open Assets:Bank

2024-01-01 open Equity:Opening-Balances

2024-01-01 * "Opening Balance"

  Assets:Bank  1000.00 USD

  Equity:Opening-Balances

======================================

将其保存为某个文件（例如 tst.bean）

然后运行：

 bean-query tst.bean

或

python -m beanquery tst.bean

确认您看到类似以下的提示：

Input file: "Beancount"

Ready with 3 directives (2 postings in 1 transactions).

beanquery>

恭喜！安装成功。

如果出于任何原因您仍希望单独安装 beancount，可以按如下方式操作：

pip install beancount

或

python -m pip install beancount

beancount v2 

要安装 beancount 的最后一个 v2 版本，请执行以下操作：

pip install "beancount<3"

或

                python -m pip install "beancount<3"

原生开发环境安装 

安装编译器 

使用 pip 安装此包时，安装过程中需要编译部分 C++ 代码，这要求计算机上已安装合适的编译器；否则您将收到关于缺少 vsvarsall.bat 或 cl.exe 的错误信息。

要为 Python 编译 C++ 代码，您需要安装与您的 Python 安装所用相同主版本的 C++ 编译器。您可以在控制台中运行 python，并查找类似 [MSC v.1900 64 bit (AMD64)] 的文本，以确定您的 Python 发行版所使用的编译器。本例中为 v.1900。

根据此数字，在此处查找所需的 Visual C++ 版本 here。由于只要前两位数字相同，不同版本通常兼容，因此理论上您可以使用 1900 至 1999 之间的任意 Visual C++ 编译器。

根据我的经验，Python 3.8 和 3.6 均使用 MSC v.1900 编译，因此您可以选择以下任一方式满足此要求：

安装独立的 Visual Studio 2017 生成工具，或
安装独立的 Visual C++ 生成工具 2015，或
修改现有的 Visual Studio 2017 安装
- 从 添加或删除程序 启动 Visual Studio 2017 安装程序
- 选择 单个组件
- 在 编译器、生成工具和运行时 下勾选 VC++ 2017 版本 15.9 v14.16 最新 v141 工具 或更高版本
- 安装
Visual Studio 2019、2022
- 添加 C++ 生成工具：C++ 核心功能、MSVC v142 生成工具

如果安装后 cl.exe 不在您的路径中，请运行 Visual Studio 开发者命令提示符，并在其中执行命令。

安装 winflexbison 

下载 winflexbison 的最新版本的 zip 文件

https://github.com/lexxmark/winflexbison/releases

将压缩包解压到某个目录（例如 C:\Program Files (x86)\winflexbison）

更新 Path 环境变量，将该目录包含在内（例如 ‘C:\Program Files (x86)\winflexbison’）

重启计算机

打开命令提示符

执行命令

win_bison --version

确认您能获得 win_bison 的版本响应

安装生成工具 

python -m pip install meson-python meson ninja

获取并安装 beancount 

从 GitHub 获取 beancount 的最新版本并进行构建

git clone https://github.com/beancount/beancount.git

cd beancount

以可编辑模式从源码安装 beancount

python -m pip install --no-build-isolation -e .

测试 beancount 

安装 pytest

python -m pip install pytest

进入该目录并运行单元测试

cd beancount

python -m pytest

确认大多数测试已通过（截至 2024 年 11 月，约 1100 个测试中约有 70 个在 Windows 上失败，这主要与单元测试假设 POSIX 环境有关，请参见问题 222 和 550）

使用 Cygwin 

Windows 安装当然有所不同。如果您使用 Cygwin，这将非常简单。您只需先准备您的机器。具体方法如下。

安装最新版 Cygwin。这可能需要一些时间（会下载大量内容），但无论如何都物有所值。但在开始安装前，请确保在 setup.exe 提供的界面中手动启用以下包（默认未选中）：
- python3
- python3-devel
- python3-setuptools
- git
- make
- gcc-core
- flex
- bison
启动一个新的 Cygwin bash 终端（桌面上应该会有一个新图标），然后通过运行以下命令安装 pip3 安装工具：
easy_install-3.4 pip
请确保使用与您安装的 Python 版本匹配的 easy_install 版本，例如，如果您安装了 Python 3.8，则使用 easy_install-3.8，以此类推。

此时，您可以直接按照前几节的说明操作，从“使用 pip 安装 Beancount”开始。

使用 WSL 

新发布的 Windows 10 年度更新带来了 WSL（Windows 子系统 for Linux），其中包含 Windows 上的 Ubuntu bash（安装说明及其他信息请访问 https://msdn.microsoft.com/commandline/wsl/about）。

这使得从 bash 安装 Beancount 变得非常简单：

sudo apt-get install python3-pip
sudo pip3 install m3-cdecimal
sudo pip3 install beancount --pre

虽然它并非完全“Windows 兼容”，因为它运行在 pico 进程中，但这种方式为 Windows 用户提供了便捷的 Linux 命令行体验。(贡献者：willwray)

检查您的安装 

您应该能够运行本文件中提到的二进制文件。例如，运行 bean-check 应该会产生类似以下的输出：

$ bean-check

usage: bean-check [-h] [-v] filename
bean-check: error: the following arguments are required: filename

如果成功，您可以前往教程，开始学习 Beancount 的使用方法。

报告问题 

如果您需要报告问题，请发送邮件至邮件列表，或在 Github 上提交工单。运行以下命令可以列出您计算机上已安装的依赖项及其版本，建议在提交错误报告时附上该命令的输出结果：

python3 -m beancount.scripts.deps

使用 uv 的替代安装方式 

从 Astral 网站安装 uv。
使用 uv 安装 Beancount

uv tool install beancount

uv tool install beanquery

这将安装二进制文件（Windows 上为 .exe 文件）并将其添加到您的 PATH 环境变量中，安装完成后即可直接运行以下命令：

beancount v3.1.0

bean-check.exe
bean-doctor.exe
bean-example.exe
bean-format.exe
treeify.exe

beanquery v0.2.0

bean-query.exe

编辑器支持 

目前支持以下一些编辑器：

Emacs 支持由独立仓库提供。有关安装说明，请参阅快速入门文档。
对使用 Sublime 编辑的支持由Martin Andreas Andersen提供。请参阅他的 GitHub 仓库。
对使用 Vim 编辑的支持由Nathan Grigg提供。请参阅他的 GitHub 仓库。
Visual Studio Code 目前有两个可用的扩展程序，均已通过 Linux 测试。
- Beancount，支持语法检查（bean-check）以及账户、货币等功能。它不仅允许选择现有的开放账户，还能显示其余额和其他元数据，非常有用！
- Beancount 格式化工具，可使用 bean-format 对整个文档进行格式化，对齐数字等。

如果遇到问题 

如果遇到任何安装问题，请提交工单或发送邮件至邮件列表。

安装后使用 

通常情况下，位于 beancount/bin 下的脚本会自动安装到您的可执行路径中。例如，您应该可以直接在命令行中运行“bean-check”。

安装 Beancount

发布版本

获取方式

安装方法

安装 Python

安装 Beancount

使用 pipx 安装 Beancount

使用 pip 安装 Beancount

从仓库使用 pip 安装 Beancount

从源码安装 Beancount

使用 pip3 从源码构建并安装 Beancount

为开发安装

开发所需依赖项

从发行包安装

Windows 安装

beancount v3

beancount v2

原生开发环境安装

安装编译器

安装 winflexbison

安装生成工具

获取并安装 beancount

测试 beancount

使用 Cygwin

使用 WSL

检查您的安装

报告问题

使用 uv 的替代安装方式

编辑器支持

如果遇到问题

安装后使用

安装 Beancount 

发布版本 

获取方式 

安装方法 

安装 Python 

安装 Beancount 

使用 pipx 安装 Beancount 

使用 pip 安装 Beancount 

从仓库使用 pip 安装 Beancount 

从源码安装 Beancount 

使用 pip3 从源码构建并安装 Beancount 

为开发安装 

开发所需依赖项 

从发行包安装 

Windows 安装 

beancount v3 

beancount v2 

原生开发环境安装 

安装编译器 

安装 winflexbison 

安装生成工具 

获取并安装 beancount 

测试 beancount 

使用 Cygwin 

使用 WSL 

检查您的安装 

报告问题 

使用 uv 的替代安装方式 

编辑器支持 

如果遇到问题 

安装后使用 