1. 建虚拟环境
用 venv 或 conda 隔离依赖，避免与系统 Python 的包互相污染。同一台机器上跑多个量化项目时，各自独立环境还能让后续升级与回滚都更安全。
Installation
vectorbt 安装教程：Windows/Linux、Numba 与 Rust 依赖
社区版基础包先在隔离 Python 环境中安装；Rust 与 full extras 是可选路线，不是安装成功的前置条件。Numba 首次调用可能有编译预热，遇到编译或二进制兼容错误时，先核对 Python、NumPy、Numba 与 vectorbt 版本组合，再判断是否需要 Rust。本页列出安全安装顺序、验证命令和常见失败分流。
pip install
Rust 引擎扩展
Full 集成扩展
import 自检
Options
vectorbt 安装方式有哪些？基础版、Rust 版与 Full 版对照
安装命令来自官方 README 安装段，[rust]、[full] 是 pip 的 extras 写法，换环境或换 shell 时以官方文档与实际终端提示为准。
| 安装方式 | 命令与内容 | 适用场景 | 注意点 |
|---|---|---|---|
| 基础版 | pip install -U vectorbt：只装核心库与 pandas / NumPy / Numba | 大多数回测与策略研究，先装这个把流程跑通 | 首次调用指标或回测时，Numba 要即时编译，会有一次性的预热停顿 |
| 升级到最新 | 仍用同一条基础命令：pip 的 -U 参数会把已安装的包升级到最新版本，不必重复指定包名 | 已经装过、想跟进官方修复与新特性 | 升级前后都在同一个虚拟环境内操作，别动系统 Python 里的包 |
| Rust 引擎版 | "vectorbt[rust]"：在核心库上追加可选的 Rust 预编译引擎 | 反复跑大量回测、不想每次新进程都等 JIT 预热 | 需要平台有可用的预编译包或本地 Rust 工具链；装不上可直接退回基础版，功能不受影响 |
| Full 集成版 | "vectorbt[full]"：在核心库上追加 TA-Lib、Pandas TA 等可选集成 | 需要完整指标生态，或让第三方指标直接接入向量化流程 | TA-Lib 依赖系统级 C 库，这一步是安装失败最集中的环节 |
| Full + Rust | "vectorbt[full,rust]"：可选集成与预编译引擎一次装齐 | 既要多指标生态，又在意回测性能 | 依赖树庞大，最容易和已有环境冲突，建议在干净环境里装 |
| 虚拟环境内安装 | 先用 venv 或 conda 建好隔离环境，再在其中执行上面任意一条命令 | 多项目并行、需要固定依赖版本的场景 | 每个环境都要重装一遍并占用磁盘；换环境时记得重新激活，别用成系统解释器 |
选型建议：先用基础版把「取数 → 算指标 → 出信号 → 回测」跑通，再按实际瓶颈决定是否追加 Rust 引擎或 full 集成。可选依赖装不上时，退回基础版继续研究通常不影响结论。
Steps
vectorbt 安装步骤怎么走？建议虚拟环境
vectorbt 的安装五步按顺序做，每步都有可验证的结果；具体命令见上表，版本与依赖约束以官方 README、PyPI 页面为准。
2. 安装核心库
激活环境后执行基础版安装命令，pip 会自动解析并拉取 pandas、NumPy、Numba 等核心依赖。国内网络较慢时可先配好镜像源，避免中途超时导致半装状态。
3. 按需加可选扩展
需要预编译加速或第三方指标生态时，把命令换成对应的 extras 写法。可选依赖装不上不影响基础功能，可以先跑通研究流程再回头补。
4. 验证安装
用解释器直接导入主库并打印版本号，能打印出版本号就算装成功。这一步同时能确认 pip 装到的解释器与运行脚本的解释器是同一个。
5. 跑通最小回测
装完别急着写策略，先用一段买入并持有示例跑一次组合回测，确认数据、指标、回测链路都可调用，再进入正式研究。
Prerequisites
vectorbt 在 Windows/Linux 的前置条件怎么检查？
先确认 Python、pip 和虚拟环境，再选择基础包或可选 extras。不同平台 wheel 与依赖支持随版本变化，准确范围以 PyPI 和官方安装说明为准。
| 依赖 | 作用 | 是否必需 | 不满足时的现象 |
|---|---|---|---|
| pandas | DataFrame 与访问器的载体，指标与回测都挂在它上面 | 必需 | 主库导入即失败，数据框访问器不可用 |
| NumPy | 向量化数组运算的底层 | 必需 | 与环境里已有版本冲突时，导入报二进制不兼容类错误 |
| Numba | 指标与回测的即时编译加速 | 必需 | 首次计算长时间无输出（正在编译），或版本不匹配导致编译失败 |
| Rust 引擎 | 预编译加速，减少 JIT 预热 | 可选 | 未安装时自动回落到 Numba，功能不受影响，只是首次运行更慢 |
| TA-Lib / Pandas TA | 第三方指标集成 | 可选 | 装 full 扩展时编译失败，通常卡在 TA-Lib 的 C 库 |
| Python 解释器 | 运行环境本体，版本要求以官方 PyPI 页标注为准 | 必需 | 版本过低时 pip 直接拒绝解析依赖，提示无法满足版本要求 |
| 磁盘与内存 | 多环境、多套依赖占空间；大规模参数广播扫描吃内存 | 视用法 | 扫描规模过大时可能出现内存不足，进程被系统终止 |
License 限制：本项目的许可是 Apache 2.0 with Commons Clause（Fair Code）：源码公开可免费使用，但不得销售主要基于此软件的产品或服务；可选依赖可能受更严格的许可约束。做商业产品或服务前需按官方 LICENSE 原文自行评估合规。
Scene
哪种 vectorbt 安装方式适合你？
vectorbt 的三种安装选择对应三种使用强度，不必一次装到最全。
选基础版
只想跑通回测、做策略研究，基础版最省事：核心库的即时编译在首次完成编译后，速度已足够支撑大多数研究场景，后续要加速也能随时追加。
选 Rust 版
如果你反复跑大量回测、介意每次新进程都要等编译预热，就加装 Rust 引擎。它改变的是「启动到出结果」的时间，不改变策略写法与结果口径。
选 Full 版
需要 TA-Lib、Pandas TA 这类完整指标生态，或想让第三方指标直接进入向量化流程，就装 full 扩展。装之前先确认系统具备编译 TA-Lib C 库的条件。
Troubleshooting
vectorbt 安装报错与排查
下表是 vectorbt 安装环节最常遇到的现象，按「处理方式」逐条试；报错原文与新版行为请以官方文档为准。
| 现象 | 可能原因 | 处理方式 | 预防 |
|---|---|---|---|
| 依赖冲突、pip 解析失败 | 已有环境里 pandas / NumPy 版本被其他包钉死 | 新建虚拟环境重装基础版再逐项加依赖 | 每个项目独立环境，别在系统 Python 上装 |
| Rust 引擎安装或编译失败 | 缺少编译工具链，或当前平台没有可用预编译包 | 退回基础版，即时编译已能满足多数研究 | 先用基础版跑通，再按需追加可选扩展 |
| TA-Lib 相关安装失败 | 缺少 TA-Lib 的 C 库 | 先装 C 库再重装 full，或改用 Pandas TA，或先不装 full | 非必需的指标生态就不要动 full 扩展 |
| 下载超时、连接失败 | 网络受限，或默认源在国内较慢 | 配置国内镜像源后重试，必要时清理 pip 缓存 | 安装前先配好镜像源，避免半装状态 |
| 权限错误（Permission denied） | 包装进了系统 Python 目录 | 在虚拟环境内安装，或使用用户级安装参数 | 始终在 venv / conda 环境里安装 |
| 导入报错（ModuleNotFoundError） | 装包的解释器与运行脚本的解释器不一致 | 用与运行一致的解释器重装，并核对 IDE 的解释器设置 | 安装时统一用 python -m pip 的形式，避免路径漂移 |
| 升级后行为异常或旧版残留 | 旧版本文件残留，或多个环境混用 | 卸载后重装基础版，或直接重建虚拟环境 | 升级在虚拟环境内做，升级前记下当前版本号 |
Self-check
vectorbt 装好后怎么做自检？逐条命令与预期输出
六项自检从「环境对不对」到「最小回测能不能跑」，按顺序执行即可确认装好；命令里的版本号输出会随官方发布变化，属正常。
| 检查项 | 命令 | 预期输出 | 不通过的常见原因 |
|---|---|---|---|
| 解释器与 pip 是否匹配 | python -m pip --version | 打印 pip 版本，并显示所属解释器的路径 | 路径指向系统 Python → 虚拟环境没有激活 |
| 主库能否导入 | python -c "import vectorbt as vbt; print(vbt.__version__)" | 打印版本号即成功（版本号随官方发布变化） | 报 ModuleNotFoundError → 装到了另一个解释器 |
| 核心依赖是否齐备 | python -c "import pandas, numpy, numba; print(pandas.__version__, numpy.__version__, numba.__version__)" | 依次打印出三个核心依赖的版本号 | 任一导入失败，说明核心依赖没装全或被其他包升级破坏 |
| 主要模块是否可用 | python -c "import vectorbt as vbt; print(vbt.MA, vbt.Portfolio)" | 打印出指标与组合回测的类对象 | 属性报错说明安装不完整，按上面步骤重装基础版 |
| 可选指标集成是否生效 | python -c "import talib"（仅在装了 full 时执行） | 无报错即 TA-Lib 可用 | 报 ModuleNotFoundError → 当前是基础版，属正常，可按需再装 |
| 最小回测能否跑通 | 用一段买入并持有示例跑组合回测（见快速上手页） | 能打印出净值与绩效统计 | 首次运行卡顿属编译过程；若报错则回到排查表逐条定位 |
自检口径说明：上面命令均在已激活的虚拟环境内执行，输出的版本号会随官方发布变化，不构成对特定版本的承诺；接口名与行为以官方 README、官方文档为准。若你只想免部署做量化研究、不想维护 Python 环境，可以看对比页列的本机量化技能路线——vectorbt 与 EasyClaw 无已证实集成，两条路线各自独立。
FAQ
常见问题
安装失败怎么办？
最常见的原因是依赖冲突或缺少编译工具链。建议先在全新虚拟环境里装基础版，确认能导入后再逐项追加可选依赖；若失败点在 Rust 引擎或 TA-Lib，先确认系统是否具备对应的编译条件，或退回基础版继续研究。具体报错含义与新版处理方式以官方 README、PyPI 说明为准。
必须装 Rust 引擎吗？
不必。Rust 引擎是可选的预编译加速项，未安装时框架会自动回落到 Numba 即时编译，功能不受影响，只是首次运行多一次编译停顿。只有对反复启动的耗时非常敏感时才值得追加，是否需要与平台预编译包支持情况以官方文档为准。
支持哪些 Python 版本？
请以官方 README 与 PyPI 页面标注的版本要求为准——上游会随版本升级调整支持范围，照抄别人的版本号容易踩坑。实践上建议在虚拟环境中让 pip 自动解析依赖，解析通过即说明当前解释器版本可用。
需要额外装 TA-Lib 吗？
不是必需。核心库自带的指标与信号工具已能覆盖常见研究需求；TA-Lib、Pandas TA 属于可选集成，装 full 扩展时才引入。TA-Lib 依赖系统级 C 库，装不上的话可以用 Pandas TA 替代，或以官方文档给出的方式处理。
装完可以直接实盘交易吗？
不能。它是向量化回测与策略研究库，不内置券商下单通道，实盘需要自行对接交易接口，并自行承担真实资金风险。若你只想快速做研究与选股、不想维护 Python 环境，可参考本机量化技能路线的对比页；两条路线相互独立，二者无已证实集成；功能范围以官方 README 与文档为准
商业使用要注意什么？
它的许可是 Apache 2.0 with Commons Clause：源码公开可免费使用，但不得销售主要基于此软件的产品或服务，具体以官方 LICENSE 原文为准。若计划做成对外收费的产品或内部业务系统，请先按原文评估合规，必要时考虑官方的商业版本。