MEASURED ON WINDOWS · PYTHON 3.11.9
QuantsPlaybook 安装与环境：先判断装得上，再谈跑得通
这个项目没有 pip 包、没有版本号，安装的真实含义是「克隆仓库 + 给某个案例单独建一个环境」。本页用本机实测结果告诉你：哪些案例的依赖能解析、哪些会报错、报错原文是什么。
- QuantsPlaybook 没有 pip 包：仓库根无
setup.py/pyproject.toml/ 根级requirements.txt。 - 22 套 requirements各自独立，
==pin 共 51 个、包名 58 个。 - 同一仓库里 numpy 有 6 种 pin、pandas 有 9 种 pin，不可能共用一个环境。
- 本机实测：4 套可解析、3 套直接失败，失败原因各不相同。
本机实测结论有哪些？
pip install --dry-run 实测结果绘制的判定示意图（2026-09-29）；结果随依赖版本变化。INSTALL REALITY
QuantsPlaybook 的「安装」到底指什么？三种说法对照
官方 README 的「快速开始」只有三行 pip install。实际执行时你会发现，那三行既不完整也不够用。
| 环节 | 官方 README 的说法 | 实际情况（本站核验） | 你该怎么做 |
|---|---|---|---|
| 获取代码 | git clone 仓库 | 仓库 pack 约 617 MB，文件树内文件合计约 1.36 GB，单文件峰值 95 MB | 浅克隆或只取需要的目录；公开 issue #4 就是「无法下载项目」 |
| 安装依赖 | pip install pandas numpy matplotlib seaborn + pip install qlib backtrader alphalens empyrical | 这 9 个包没有任何版本号；而案例目录里的 requirements.txt 钉的是 2020–2021 年的具体版本，二者常常冲突 | 以案例目录自己的 requirements.txt 为准，忽略 README 的通用清单 |
| 数据客户端 | pip install jqdatasdk 或 pip install tushare | 实测仓库里至少并存 9 种取数方式，且部分案例需要自建数据库、DolphinDB 或作者私有模块 | 先看数据页确定案例要哪个源，再装对应客户端 |
| Python 版本 | 「Python 3.8+」 | 不同案例要求不同：老案例实际只支持到 3.8/3.10，新案例写明 3.10+（并注明曾在 3.13.11 上跑通） | 一个案例一个虚拟环境，别用系统 Python 硬套 |
| 第一个案例 | cd C-择时类/RSRS择时指标/py 然后 jupyter notebook RSRS.ipynb | 该路径与 Notebook 文件确实存在（已核对）；但目录里没有 requirements.txt，依赖要自己推断 | 从自带 requirements.txt 的案例入手 |
核对方式：README 原文逐句比对 + 固定 commit 文件树校验路径存在性 + 22 份 requirements.txt 全文解析。
PYTHON VERSION GATES
Python 版本怎么选？QuantsPlaybook 的 wheel 覆盖门槛
下表把同一仓库里的依赖按「能装到哪个 Python」分档。判断依据是 PyPI 上该版本是否提供对应解释器的 wheel，以及实测报错原文。
| 依赖档位 | 代表 pin | 可用 Python（有 wheel 的最高版本） | 对案例的影响 |
|---|---|---|---|
| 3.8 时代 | numpy==1.20.3/1.21.5、pandas==1.2.4/1.4.1、numba==0.53.1、pyqlib==0.9.1/0.9.3 | cp38（部分到 cp310） | 老案例基本只能在 3.8–3.10 上跑；3.11 起多数需要源码编译 |
| 3.10 时代 | scikit_learn==1.0.2/1.1.1、statsmodels==0.12.2、matplotlib==3.3.4 | cp38 / cp310 | 如果一定要跑这批案例，把解释器压到 3.10 最省事 |
| 3.11 时代 | numpy==1.23.5、pandas==1.5.3、torch==2.0.0、scipy==1.10.1 | cp311 | 这类案例在 3.11 上通常可解析，但装完后可能与「3.8 时代」的案例互斥 |
| 3.12 时代 | pyqlib==0.9.6、pandas==2.2.2/2.2.3、statsmodels==0.14.2 | cp312 | 新案例（含 SAE 择时）在这一档依赖最新 |
| 3.13 之后 | numpy>=1.24、pandas>=2.1、torch>=2.2、ta-lib>=0.6 | cp313 | SAE 案例文档写明「现有 notebook 使用 Python 3.13.11 成功运行过，但这不是所有依赖组合的兼容性保证」 |
来源：PyPI 上每个 pin 的文件列表（cp38/cp310/cp311/cp312/cp313 与 win_amd64 覆盖）+ 本机 dry-run 报错原文。口径提醒：这里说的「有 wheel」指该版本至少发布过对应解释器的二进制包，不代表你的平台一定有。
DRY-RUN MATRIX
QuantsPlaybook 的依赖装得上吗？本机实测矩阵
测试方式：pip install --dry-run --ignore-installed --only-binary=:all: --python-version <v> -r <该案例的 requirements.txt>，不对系统做任何安装。下表是逐套实测结果。
| 代表案例 | Python 3.10 | Python 3.11 | Python 3.12 | 本机 3.11.9（允许源码包） | 关键结论 |
|---|---|---|---|---|---|
筹码因子（Qlib 栈） | 失败 | 失败 | 失败 | 失败 | numba==0.56.4 源码构建报「only versions >=3.7,<3.11 are supported」 |
QRS择时信号 | 失败 | 失败 | 失败 | 通过 | 只在允许源码包时通过：empyrical==0.5.5 没有 wheel |
基于稀疏自编码器的指数择时 | 通过 | 通过 | 通过 | 通过 | 用 >= 下界，最宽松的一档 |
SignalMaker | 失败 | 失败 | 失败 | 通过 | TA_Lib==0.4.32 无 wheel；3.12 下 numpy==1.23.5 不可用 |
相对旋转图RRG行业轮动 | 失败 | 通过 | 通过 | 通过 | numpy==2.4.3 不支持 3.10 |
个股动量效应的识别及球队硬币因子 | — | — | — | 失败 | 报「Could not find a version that satisfies the requirement pyqlib==0.9.3 (from versions: 0.9.6, 0.9.7)」 |
特征分布建模择时 | — | — | — | 失败 | 构建 numpy 时报「ModuleNotFoundError: No module named 'distutils.msvccompiler'」 |
实测环境：Windows + Python 3.11.9 + pip（清华镜像 + PyPI 双索引），日期 2026-09-29。「失败」只说明在这台机器、这一天的解析结果；换 Python 版本、换平台或等依赖更新后结果可能不同，请以自己的环境为准。
WHY IT FAILS
QuantsPlaybook 装不上时报什么错？四类原因与处理
把报错原文抄下来，比记「装不上」三个字有用得多。下面四类覆盖了本站实测遇到的全部情况。
| 报错原文（节选） | 真实原因 | 处理办法 | 残留下什么问题 |
|---|---|---|---|
RuntimeError: Cannot install on Python version 3.11.9; only versions >=3.7,<3.11 are supported. | numba==0.56.4（2022 年版本）没有 3.11 的轮子，源码构建时自带版本检查 | 把解释器降到 3.10 或更低；或换成新版 numba（但会牵动 numpy/scipy 全体版本） | 换成新版后，该案例的其它 pin 可能集体不兼容 |
ERROR: Could not find a version that satisfies the requirement pyqlib==0.9.3 (from versions: 0.9.6, 0.9.7) | 该版本在 3.11 环境下不可见（PyPI 上 0.9.3 的发行文件不适用于该解释器） | 改用 3.8 解释器，或把依赖改成能装上的 pyqlib 版本 | 改版本后 Qlib 的 API 与案例代码不保证兼容 |
ModuleNotFoundError: No module named 'distutils.msvccompiler' | 旧版 numpy（如 1.22.3）在 3.11 上没有 wheel，只能源码编译，而新版 setuptools 移除了该模块 | 降到 3.10 用现成 wheel；或先安装兼容的 setuptools | 强制装老 setuptools 可能影响同环境其它包 |
ERROR: No matching distribution found for alphalens==0.4.0（在只允许二进制包时） | alphalens==0.4.0、empyrical==0.5.5、ta_lib 全系都只发布源码包 | 允许源码安装（需要 C/C++ 编译环境与 TA-Lib 系统库） | Windows 上编译 TA-Lib 是最常见的一道坎 |
所有报错原文均来自本机实跑输出，未做改写。这些是环境层的问题，与案例的策略逻辑无关——也就是说，「装不上」不等于「策略不对」，只是你还没到判断策略那一步。
DEPENDENCY COLLISIONS
为什么要一个案例一个环境？6 种 numpy、9 种 pandas
把 22 份 requirements.txt 合并统计后，冲突是结构性的，不是偶然。
| 包 | 仓库内出现的 pin 数 | 举例（版本跨度） | 冲突后果 |
|---|---|---|---|
pandas | 9 | 1.2.4 / 1.4.1 / 1.5.3 / 2.2.3 / 2.3.3 / 3.0.2 | 老案例代码大量使用被移除的 API；新案例代码在新 pandas 上写 |
numpy | 6 | 1.20.3 / 1.21.5 / 1.22.3 / 1.23.5 / 2.4.3 / 2.4.4 | numpy 2.x 与 1.x 的 ABI 不兼容，二进制扩展包（numba/pyarrow 等）必须跟着重建 |
matplotlib | 10 | 3.3.4 / 3.7.1 / 3.9.2 / 3.10.9 | 绘图 API 与默认样式有变化，出图脚本可能报参数错误 |
scipy / statsmodels / scikit-learn | 各 4–6 | scipy 1.6.2 → 1.17.1 | 统计函数签名变化；与 numpy 版本强绑定 |
qlib 两个包名 | 2 | qlib==0.0.2.dev20 与 pyqlib==0.9.1 同时出现在同一个案例 | 两个包同名不同源，安装顺序与覆盖关系需要自己确认 |
ta_lib / TA-Lib | 4 | 0.4.19 / 0.4.21 / 0.4.24 / 0.4.32（另有新案例写 >=0.6） | 拼写不同（下划线/连字符）会装成不同包；全部需要系统级 C 库 |
结论：不存在一个能同时满足所有案例的环境。可行做法是按案例建虚拟环境；如果你只想用其中的工具包（hugos_toolkit、SignalMaker），依赖面会小很多，参见工具包页。
WINDOWS WALKTHROUGH
QuantsPlaybook 在 Windows 上怎么建环境？四步与预期输出
以自带 requirements.txt 且依赖相对现代的案例为例（如 相对旋转图RRG行业轮动）。命令刻意写成「先进目录再执行」，避免中文路径直接当参数传入报错。
py -3.11 -m venv .venv → .venv\Scripts\activate。预期输出：命令提示符前出现 (.venv)；python -V 显示你选的版本。
python -m pip install --dry-run -r requirements.txt。预期输出：结尾出现 Would install …；若报 Could not find a version 或 error: subprocess-exited-with-error，先按上面的报错对照表处理，别硬装。
python -m pip install -r requirements.txt，然后 python -c "import pandas, numpy; print(pandas.__version__, numpy.__version__)"。预期输出：两个版本号，且与 requirements.txt 里写的一致。
按数据页确认该案例要什么数据，配好凭据或下载离线快照，再用同一环境的 Jupyter 打开 Notebook，只跑第一格取数验证。预期输出：一个带时间索引、列名符合案例 README 描述的数据表。
为什么先 dry-run
本机实测发现 7 套代表依赖里有 3 套无法解析。先跑 dry-run 只要几十秒，能避免装到一半失败后留下半残环境。
中文路径的坑
本机实测：把含中文的路径直接作为参数传给可执行文件会失败。稳妥写法是先 cd /d 进目录，再执行 ASCII 名称的脚本。
装不上不是你的错
这些失败来自依赖年代久远与平台限制，不是操作错误。选对 Python 版本能解决大部分问题：老案例压到 3.8–3.10，新案例用 3.11+。
FAQ
QuantsPlaybook 安装与环境常见问题
QuantsPlaybook 能 pip 安装吗？
不能。仓库根目录没有 setup.py、pyproject.toml、根级 requirements.txt 或 environment.yml，PyPI 上也没有同名包，仓库里 0 tag、0 release。「安装」实际指：克隆仓库，然后给某一个案例目录单独建环境。
QuantsPlaybook 我该用哪个 Python 版本？
取决于你要跑的案例，不看仓库整体。判据是案例目录自己的 requirements.txt：钉在 2020–2021 年版本的多半只能到 3.8–3.10；用 >= 下界的新案例（如 SAE 择时）在本机 3.11.9 上解析通过，文档还写明曾在 3.13.11 上跑通。本站实测最稳的策略是一个案例一个虚拟环境。
QuantsPlaybook 为什么我安装时报 numba 或 pyqlib 的错？
这两类是本站实测最常见的失败。前者因为 numba==0.56.4 自带 Python 上限检查，在 3.11 上会直接报「only versions >=3.7,<3.11 are supported」；后者因为老版 pyqlib 在 3.11 环境下不可见，报「Could not find a version that satisfies the requirement pyqlib==0.9.3」。两者都不是代码问题，是版本问题。
QuantsPlaybook 一定要装 TA-Lib 吗？
只有部分案例需要，但它是最难装的一个：ta_lib 的 0.4.x 全系、以及新案例写的 TA-Lib>=0.6 都没有现成的 Windows 轮子，需要本机编译并依赖系统级 TA-Lib C 库。如果案例只是用它算均线/RSI 之类指标，可以考虑用其它库替代并改造代码。
QuantsPlaybook 能不能把所有案例的依赖装到一个环境里？
不建议，而且实际做不到。本站统计：22 份 requirements.txt 里 numpy 有 6 种 pin、pandas 有 9 种 pin、matplotlib 有 10 种，还有同一个案例同时安装 qlib 与 pyqlib 的情况。numpy 1.x 与 2.x 的二进制扩展不兼容，合并必然导致部分案例失效。
QuantsPlaybook 仓库里的依赖清单可信吗？
基本可信但不能照抄：本站逐个查了 51 个 == pin，全部存在于 PyPI 且未被 yank，说明清单本身不是编的；但约 40% 没有 wheel，且各案例之间互斥。另有 22 个案例目录之外的文件（如 SignalMaker/requirements.txt）也需要单独看。
QuantsPlaybook macOS / Linux 会不会好一点？
本站只在 Windows + Python 3.11.9 上做了实测，没有 macOS/Linux 数据。可以确定的两点是：① 依赖没有 wheel 的问题在 Linux 上通常更容易通过源码编译解决；② ta_lib 在 Linux 上可以用系统包管理器先装 TA-Lib C 库，比 Windows 顺畅得多。具体请以你自己的环境为准。