Installation · Python 回测库

bt 安装部署：pip install bt 与源码方式教程

bt（pmorissette/bt）的官方安装入口只有一行 pip install bt，但真正卡住人的通常不是这一行命令，而是三件容易被忽略的事：它下载的是与 Python 版本和平台绑定的编译轮子、pandas / numpy 没有直接写在运行时依赖里、装完还要确认能 import 到编译核心。本页把安装拆成可对照执行的检查表：安装方式对照、依赖边界、编译轮子说明、五步安装验证、七项自检清单与报错排查表，命令与版本边界都以官方仓库、PyPI 包（1.2.3 实测）与官方文档为准。

看安装方式对照看装完自检清单

官方：pip install btPython：>= 3.9（覆盖 3.9–3.13）版本：1.2.3（2026-09-11 发布，以 PyPI 为准）安装后仍需自备价格数据与算法链

pip install bt官方安装方式

指定版本复现历史结论

源码安装git+ 仓库地址

虚拟环境先隔离再安装

安装路径示意（pip / 指定版本 / 源码 / 虚拟环境），基于 bt 官方 README 与 PyPI 包实测；版本与依赖约束以官方为准。

Options

bt 的安装方式怎么选？几条路径对照

官方 README 给出的安装入口是 pip；下表把常见路径放在一起比较，重点看「什么时候用」和「容易踩什么」。

安装方式	命令	适用场景	注意点
pip 基础安装	`pip install bt`	绝大多数使用场景，官方推荐入口	装到当前解释器下；多环境机器先确认 `python` 与 `pip` 是否指向同一套环境
升级到最新发布版	`pip install -U bt`	已装过旧版本，想跟官方发布版	升级后重跑导入自检；v1.2.3 把核心迁移到 numpy 数组，跨大版本升级建议先记录旧结论
虚拟环境内安装	`python -m venv .venv` 激活后再 pip	一台机器跑多个项目、依赖易冲突	务必先激活再安装，否则会装进全局解释器；回测结论要连同环境一起记录
指定版本安装	`pip install bt==<版本号>`	复现某次回测、对照历史代码	版本号只能取自 PyPI 发布列表；本页不背书任何具体号段
从 GitHub 安装开发主线	`pip install git+https://github.com/pmorissette/bt`	想用未发布改动、给上游提补丁	主分支行为可能变化，回测结论要记录所用提交；长期依赖请回到发布版
源码可编辑安装	克隆仓库后 `pip install -e .`	边读源码边改实现、要调试算法类	需要能编译扩展（Cython 核心），Windows 上通常还要装 C 编译工具链
内网/镜像源安装	pip 加 `-i` 指定镜像源	公司内网或下载超时	镜像源同步时间不确定，拿到的版本可能与官方最新不同；注意轮子是否同步

先确认一件事：bt 是回测库，安装只解决「能 import」；价格矩阵与算法链需要你自己准备（数据与算法写法见「首次回测」与「算法库」两页）。

看分步安装看编译轮子说明

Environment

bt 的环境与依赖边界是什么？

下表把「装得对不对」的判断依据列出来：边界取自 PyPI 包 bt 1.2.3 元数据，最后一列写的是不满足时你会看到什么。

依赖项	边界（来源）	作用	不满足时的现象与注意点
Python	`Requires-Python >=3.9`；分类器覆盖 3.9 / 3.10 / 3.11 / 3.12 / 3.13（PyPI 元数据）	运行环境	3.8 及以下安装阶段直接失败：`No matching distribution found for bt`
ffn	运行时依赖 `ffn>=1.1.2`	绩效统计与图表；bt 还把 `ffn` 的 `data/get/merge/utils` 再导出	缺它时 `import bt` 直接失败，因为 `bt/__init__.py` 开头一行就依赖 ffn
pyprind	运行时依赖 `pyprind>=2.11`	回测进度条输出	缺它同样会导致导入失败；长回测看不到进度提示
tqdm	运行时依赖 `tqdm>=4`	进度显示（另一套实现）	缺它时导入即报错；脚本里看到的进度条来自这两个包之一
pandas / numpy	未写入运行时依赖（经 ffn 间接带入；开发 extra 才明列 `numpy>=1`、`pandas>=0.19`）	价格矩阵与数值计算	环境不完整时报 `ModuleNotFoundError: No module named 'pandas'`——建议显式安装 pandas
编译核心（Cython）	轮子里包含 `bt/core.<abi>.pyd`（如 `core.cp311-win_amd64.pyd`）	组合与数据推进的性能核心	核心与「Python 版本 + 平台」绑定；缺失或版本不匹配时导入失败
pip / 网络 / 磁盘	无特殊版本要求，安装期需要联网	下载轮子与三个依赖	下载超时表现为安装中断；无官方磁盘硬性数字，数据量大时靠内存与磁盘自行评估

边界提醒：上表约束取自 PyPI 包元数据与该版本实测，小版本变化请以官方 README、PyPI 页面与官方文档为准；本页不替代官方安装说明。遇到与本文不一致的地方，一律以官方说明为准。若机器上已装过其它数据分析库，建议先在干净虚拟环境里逐项确认，再决定是否动全局依赖——升级容易，回退往往更麻烦。

看报错排查表

Compiled wheel

为什么 bt 装的是编译轮子？版本选错会怎样

下面这张表是本页最容易被忽略的部分：pip install bt 拿到的不是纯 Python 源码包，而是与解释器和平台绑定的轮子。pip download bt 实测（2026-09-20）拿到的是 bt-1.2.3-cp311-cp311-win_amd64.whl。

场景	实际会拿到什么	现象	处理与注意点
Windows + CPython 3.11（64 位）	`bt-1.2.3-cp311-cp311-win_amd64.whl`，内含 `bt/core.cp311-win_amd64.pyd`	安装很快完成，导入正常	无需编译工具链；把轮子文件名记进环境说明，便于他人复现
其它 Python 小版本（3.9 / 3.10 / 3.12 / 3.13）	对应 abi 的轮子（命名里出现 cp39 / cp310 / cp312 / cp313）	同样秒装，前提是官方发布了该「解释器 + 平台」组合的轮子	先用 `pip download bt --no-deps` 看一眼会拿到哪个文件，是最快的确认方式
没有匹配轮子的平台或架构	回退到源码构建分支	安装过程中报编译相关错误，或提示需要编译器	装好编译工具链后重试，或在有轮子的环境里构建后再分发
Python 3.8 及以下	没有匹配项	`No matching distribution found for bt`	升到 3.9+；不要用「忽略 Requires-Python」的强制参数硬装
机器上残留旧版编译核心	旧 `core*.pyd` 未清理	升级后行为与版本说明不一致，报错指向核心符号	先 `pip uninstall bt` 再重装，确保只留一份核心文件
想确认核心文件是否在位	`bt/core.<abi>.pyd`	文件缺失时 `import bt` 失败	用 `python -c "import bt, os; print(os.path.dirname(bt.__file__))"` 打开目录核对文件清单

为什么值得单独讲：「pip 装不上」在 bt 上多数不是网络问题，而是解释器版本或平台没有对应轮子。先把「会拿到哪个轮子」确认清楚，比反复换镜像源更快定位。

看装完自检清单

Steps

分步安装与验证怎么做？五步走完

五步走完，每步给出命令、一句话说明与可验证的预期输出；命令里的版本号与依赖解析结果会随官方发布变化，属正常。

确认解释器与 pip 来源
先确认即将安装到哪个 Python 里，避免装完却在另一个环境导入。
```
python -V
python -m pip -V
```
预期输出：两条命令都打印版本号，且两条路径指向同一套 Python 环境（路径前缀一致即正常）；bt 要求 Python >= 3.9。
创建并激活虚拟环境
用 venv 隔离依赖，避免与系统或其他项目互相影响。
```
python -m venv .venv
:: Windows 激活
.venv\Scripts\activate
```
预期输出：命令行提示符前出现 (.venv)；再执行 python -V 仍是同一版本。
执行官方安装命令
安装本体；pip 会解析 ffn、pyprind、tqdm 三个运行时依赖，并拉取与你的解释器匹配的编译轮子。
```
pip install bt
```
预期输出：过程中能看到 Downloading bt-1.2.3-<abi>-<platform>.whl，末尾出现 Successfully installed bt-1.2.3 ...（版本号以 PyPI 当前发布为准）。
补装 pandas 并做导入自检
pandas 没有直接写在 bt 的运行时依赖里，显式确认一遍最省事，同时核对导入的版本。
```
pip install pandas
python -c "import bt, ffn, pandas; print(bt.__version__, ffn.__version__, pandas.__version__)"
```
预期输出：输出的版本号为 1.2.3，后两项打印 ffn 与 pandas 版本号；若报 ModuleNotFoundError，说明装到了别的环境，回到第 1 步核对。

跑通一次最小回测

用官方 README 的合成价格示例，不需要下载任何行情即可确认整条链路（策略 → 回测 → 统计）。

import numpy as np, pandas as pd, bt
prices = pd.DataFrame({"asset_a": np.linspace(100, 120, 252),
                       "asset_b": np.linspace(100, 110, 252)},
                      index=pd.bdate_range("2020-01-01", periods=252))
strategy = bt.Strategy("equal_weight", [
    bt.algos.RunMonthly(), bt.algos.SelectAll(),
    bt.algos.WeighEqually(), bt.algos.Rebalance()])
result = bt.run(bt.Backtest(strategy, prices))
result.display()

预期输出：打印出统计表与净值曲线（统计与图表由 ffn 提供）。此示例用合成价格，收益数字只用于验证链路是否通畅。

不需要激活环境时：CI 或脚本里可以直接用 python -m pip install bt 指定解释器安装，效果等同于先激活再 pip，命令细节以官方文档为准。若在 CI 里跑回测，建议把「解释器版本 + 安装命令 + 数据区间」一起写进流水线说明，别人复现结论时才不会先卡在环境上。

看首次回测执行步骤看 59 个内置算法

Self-check

装完怎么自检？七项逐条确认

装完别急着写算法链，先按这张表逐项确认；每项都有命令、预期输出和「不通过时先查什么」，比反复重装更快定位问题。

检查项	命令	预期输出	不通过时先查什么
解释器可用	`python -V`	打印版本号且 >= 3.9	PATH 里是否有更早的 Python 抢先被调用
pip 指向同一环境	`python -m pip -V`	路径与上一条解释器一致	是否用了全局 pip；改用 `python -m pip` 形式执行
包已安装	`pip show bt`	显示名称、1.2.3 与安装位置	是否在虚拟环境外执行了安装命令
可被导入且版本正确	`python -c "import bt; print(bt.__version__)"`	打印 `1.2.3`（以实际安装版本为准）	同名目录遮蔽（项目里有叫 `bt` 的文件夹）或装到了别处
三个运行时依赖在位	`python -c "import ffn, pyprind, tqdm; print(ffn.__version__)"`	无报错并打印 ffn 版本	依赖是否被手动降级；`pip check` 看有无冲突
pandas / numpy 可用	`python -c "import pandas, numpy; print(pandas.__version__, numpy.__version__)"`	打印两个版本号	bt 未直接声明这两个依赖，缺失时需显式安装
编译核心在位	`python -c "import bt, os, glob; print(glob.glob(os.path.join(os.path.dirname(bt.__file__),'core*')))"`	列出 `core.<abi>.pyd` 之类文件	核心缺失说明轮子与解释器不匹配，重装或换解释器
回测主体可运行	用合成价格执行一次 `bt.run(bt.Backtest(...))`	返回含统计的结果对象，`result.display()` 有输出	算法链是否缺少 Rebalance；价格矩阵索引是否为日期

口径说明：上表命令与类名以官方 README 与该版本包结构为准；不同小版本的提示文案可能不同，只要功能正常即可，不必逐字对照。若某一步输出与预期不符，先在干净虚拟环境里重跑一次，排除历史环境残留，再去查其它原因。

看报错排查表回到依赖边界

Troubleshooting

bt 安装报错怎么排查？

下表按「现象 → 可能原因 → 处理方式 → 预防」整理安装与导入阶段最常见的七类问题；报错原文与新版行为以官方文档为准。

现象	可能原因	处理方式	预防
`No matching distribution found for bt`	Python 低于 3.9，或所在平台没有对应轮子	换 3.9+ 解释器或新虚拟环境；确认平台架构后再装	建项目时先固定解释器版本，写进环境说明
`ModuleNotFoundError: No module named 'pandas'`	pandas 未显式安装（它不在 bt 的直接依赖里）	`pip install pandas` 后重跑导入自检	安装 bt 后紧接着补装 pandas / numpy 并记录版本
`ModuleNotFoundError: No module named 'ffn'`	依赖未装全，或被手动降级移除	`pip install -U ffn`，再用 `pip check` 看冲突	不要手工裁剪依赖；用 `pip freeze` 留档
安装卡在下载或中途断开	网络受限、镜像源不同步	换镜像源或先 `pip download bt` 再离线安装	内网机器提前准备轮子与三个依赖的安装包
权限错误，写入被拒绝	装到了系统级目录	改用虚拟环境，或加 `--user` 装到用户目录	默认在虚拟环境里安装，不直连全局站点包
导入的 bt 不是期望版本	环境里同时存在多份 bt，或旧编译核心未清理	`pip uninstall bt` 后重装，并核对 `bt.__file__` 路径	一个项目一个虚拟环境，不共用全局解释器
升级后原有回测脚本报错	新版行为变化（如核心迁移到 numpy 数组、保证金相关修复）	按官方 release 说明调整，必要时回退到之前版本对照	升级前记录当前版本、关键统计量与数据区间，便于回退比较

看首次回测回到自检清单

Other routes

bt 还有哪些安装与使用路径？

除标准 pip 安装外，还有几种常见路径；选哪条取决于你是「只想用」还是「要改」，以及网络与团队的约束。

路径	怎么做	适合谁	注意点
标准 pip 安装	虚拟环境内 `pip install bt`	只想尽快跑通回测的研究者	升级会跟随官方发布，结论要记录版本
锁定版本复现	安装时指定版本号并记录在项目说明里	要与同事或历史结论对齐	版本号需查 PyPI，本页不提供号段背书记录
GitHub 开发主线	`pip install git+https://github.com/pmorissette/bt`	想用未发布改动、要给上游提补丁	行为可能随时变化；不建议作为长期生产依赖
源码可编辑安装	克隆仓库后 `pip install -e .`	要改算法实现、要加自己的 Algo	需要可用的编译工具链；改动要与发布版分开管理
离线/内网安装	先在可联网机器 `pip download bt`，再拷贝安装	内网环境、公司代理限制	轮子与三个依赖都要一起带走，架构与 ABI 要匹配
容器化运行	在镜像里安装并固定依赖	团队统一环境、复现历史回测	镜像需自行维护；无界面环境下把出图改为输出文件

只是想验证一个想法

走标准 pip 安装即可：装好、备好价格矩阵、写一条算法链就能跑。若连环境都不想维护，可以先走免部署的问句式研究路线，但要清楚它和 bt 是两条独立路线，不能替代代码级可复现的回测。

要在团队里复用

优先「虚拟环境 + 锁定版本 + 记录数据区间」三件套，把安装命令与版本号写进项目说明；回测结论要对齐，必须同时对齐代码版本、数据区间与成本假设，否则数字没有可比性。

要改算法实现

用源码可编辑安装更直接，但请把改动与官方发布版分开管理：升级前先看自己改过哪些文件，避免覆盖后回测结论失效。只想临时验证时，也可以先在发布版上跑通再决定是否切到源码。

能力边界：bt 的定位是多资产组合回测框架（算法树 + 权重/再平衡），安装完成后仍需自备价格数据与算法链；本页描述的安装与运行完全在本地 Python 环境完成，与本机免部署技能路线之间没有已证实的集成关系。

看算法树看权重与再平衡

FAQ

bt 安装常见问题

bt 的包名是什么？和「BT 下载」是同一个东西吗？

PyPI 包名就是 bt，安装命令 pip install bt，仓库为 pmorissette/bt，是一个 Python 回测库，与 BitTorrent（种子/磁力下载）没有任何关系。包名与项目定位以官方 README 与 PyPI 页面为准。搜索教程时看到「bt」这个短词，先确认对方讲的是回测库还是下载工具。

bt 需要什么 Python 版本？

包元数据写的是 Requires-Python >=3.9，分类器覆盖 3.9 / 3.10 / 3.11 / 3.12 / 3.13。实测下载到的是与解释器和平台绑定的编译轮子（如 cp311-win_amd64），所以「版本选对」比「版本够新」更关键；具体支持范围以 PyPI 页面标注为准。

为什么装完还提示缺 pandas？

因为 bt 的运行时依赖只声明了 ffn、pyprind、tqdm 三个，pandas 与 numpy 是通过 ffn 间接带入的（开发 extra 里才明列 numpy>=1、pandas>=0.19）。环境不完整时会直接报 ModuleNotFoundError: No module named 'pandas'，显式安装一次即可；依赖声明以该版本包元数据为准。

装完怎么确认真的能用？

三步：python -c "import bt; print(bt.__version__)" 确认版本，核对 bt 目录下是否存在 core.<abi>.pyd 编译核心，再用官方 README 的合成价格示例跑一次 bt.run(bt.Backtest(...))。前两步不通过通常是环境问题，第三步不通过通常是算法链或数据格式问题，见本页自检清单。

bt 是免费的吗？可以商用吗？

bt 采用 MIT 许可（PyPI 包元数据与仓库 LICENSE 均标注 MIT），可自由使用与修改，具体条款以仓库 LICENSE 原文为准。使用第三方行情数据时，数据授权需要你自行确认，与本库许可无关。

能在本机技能里一键安装 bt 吗？

没有已证实的集成关系：bt 通过 pip 独立安装在本机 Python 环境里，本机技能提供的是另一条免部署研究路线，两者互不替代。是否存在后续集成以双方官方说明为准，本页不做任何暗示。可以确定的是：安装与运行都在你自己的环境里完成，回测结论与是否安装其它工具无关。