Alphalens · pandas 版本与报错排查
Alphalens 报错排查：真实报错原文、根因与版本边界
Alphalens 的绝大多数失败不是算法问题，而是版本断层：主库的依赖表停在 2020 年，之后 pandas 与 numpy 各有过若干次破坏性变更。这一页把仓库里真实存在的报错原文逐条列出（每条给出 issue 编号）、补上维护分支声明的版本区间，并附上本机实测的两条记录。
Alphalens 报错怎么定位：四步顺序
Alphalens 有哪些真实报错：对照表
下表的报错原文来自仓库里真实存在的 issue 标题与正文，编号可逐条核对。本站不编造报错。
| 报错原文 | 典型触发条件 | 根因 | 处理方式 | 来源 |
|---|---|---|---|---|
No such keys(s): 'mode.use_inf_as_null' | 在较新的 pandas 上运行主库 | pandas 移除了该全局选项，而库内部仍在设置它 | 改用维护分支，或把 pandas 降到库支持的年代区间 | issue #401（2023-10-12，open） |
No module named 'pandas.util._decorators' | 在 pandas 1.0 及以上导入旧版 alphalens | 该私有模块在 pandas 1.0 起被移除 | 升级到维护分支；不要试图自己补模块 | issue #394（2021-11-22，open） |
'Index' object has no attribute 'get_values' | pandas 1.0 及以上 | Index.get_values 被移除 | 同上；维护分支已处理这类 API 变更 | issue #379（2020-05-13）、#396（2021-12-05） |
ufunc 'isfinite' not supported for the input types | numpy 版本变更后运行清洗或指标计算 | numpy 对对象类型数组的有限性判断行为变化 | 确认 numpy 与维护分支声明区间一致 | issue #385（2020-09-07，open） |
ValueError: Inferred frequency None from passed values does not conform to passed frequency C | 价格或因子索引非规则交易日序列 | pandas 无法从索引推断频率，而库内部传入了固定频率 | 规整索引为规则频率，或显式传入 freq 相关参数 | issue #367（2020-04-13）、#371（2020-04-21，open） |
ValueError: freq must be Day, BDay or CustomBusinessDay | 传入非日频（如周频、月频）数据 | 库只支持特定频率枚举 | 重采样为日频，或按该 issue 的讨论配置自定义日历 | issue #382（2020-07-29）、#351（2019-09-24） |
AttributeError: 'Index' object has no attribute 'tz' | 中国市场数据、索引带时区信息 | 时区感知索引与库内部的时区处理不兼容 | 先把索引去时区（统一为 naive 时间戳）再传入 | issue #145（2017-02-27，报告者自述为中国市场数据） |
ModuleNotFoundError: No module named 'alphalens' | 装完却导入失败 | 装到了另一个解释器/虚拟环境，或当前环境未激活 | 用与安装同一个解释器执行 python -c "import alphalens" 验证 | issue #321（2018-10-11） |
cant install alphalens from pip because of outdated configparser method call | 在较新 Python 上 pip 安装主库 | 2020 年的构建脚本调用 configparser 的旧方法 | 改装维护分支；本站实测在同一环境下也遇到构建阶段失败 | issue #406（2024-06-02，open） |
create_turnover_tear_sheet 报错 / 分位累计收益图不出图 / 图不可读或空白 | tear sheet 渲染路径 | 多步骤绘图链中任一步的版本兼容问题 | 跳过报告函数，用 quantile_turnover + plotting 单独出图 | issue #341 / #377 / #380 / #369 / #370 |
Alphalens 版本矩阵：哪些组合是明确声明过的
主库从未给出兼容矩阵，维护分支把自己的边界写进了 pyproject.toml。下表把两边能核实的区间并列，空着的就是「官方未声明」。
| 依赖 | 主库 0.4.0 声明 | 维护分支 0.4.6 声明 | 实务判断 | 注意点 |
|---|---|---|---|---|
| Python | 未声明 requires_python；分类器只到 3.5 | ≥ 3.10（分类器 3.10–3.13） | 3.10 以上用维护分支，3.9 及以下两边都要实测 | 主库在 3.11 上的安装实测失败 |
| pandas | >=0.18.0（无上限） | >=1.5.0,<3.0 | 主库的无上限正是它频繁报错的根因；维护分支主动钉住区间 | pandas 3.0 尚未适配（issue #46，2026-04-20 开） |
| numpy | >=1.9.1 | Python <3.12 要 ≥1.23.5；≥3.12 要 ≥1.26.0 | 按维护分支的分档装，别硬上最新大版本 | README 另注明 numpy ≥ 2.0 需要 pandas ≥ 2.2.2 |
| 绩效指标库 | empyrical>=0.5.0（最后发布 0.5.5，2020-10-13） | empyrical-reloaded>=0.5.7 | 这条依赖是主库停更后最大的隐患之一 | 两边包名不同，不能混装 |
| 绘图与统计 | matplotlib ≥1.4.0、seaborn ≥0.6.0、statsmodels ≥0.6.1 | 同左（沿用） | 这三个包本身演进很快，出图问题多半出在这里 | 本机实测曾出现 statsmodels 与新版 scipy 不兼容导致导入失败 |
| scipy | >=0.14.0 | >=0.14.0 | 两条线都没有上限，但实际会踩到新版 scipy 的移除 API | 本机实测报错见下一节 |
Alphalens 报错怎么排查：从解释器查到数据
顺序很重要。多数人一开始就怀疑自己的因子表，实际上问题通常在依赖版本。每步都给出可执行的检查命令与判据。
确认装的是哪个包、哪个版本
执行
pip show alphalens alphalens-reloaded与python -c "import alphalens; print(alphalens.__file__)"。判据：安装路径与当前解释器一致；若两者都装了，先卸载主库避免混用。确认解释器与 pandas / numpy 版本落在声明区间内
执行
python -c "import sys, pandas, numpy; print(sys.version, pandas.__version__, numpy.__version__)"。判据：Python ≥3.10、pandas 落在 1.5–2.x、numpy 按上表分档。不在区间内就先调整环境，别继续往下查。确认索引与频率可推断
检查索引是否为规则的交易日序列、是否带时区。判据：
pandas.infer_freq(idx)能返回值；带时区就先去时区。这一步对得上，就能避开频率与时区两类报错。最后才怀疑数据与参数
确认列名与索引层名一致、quantiles 与 bins 没有同时传、max_loss 没有把合法数据判成异常。判据：清洗函数能打印出合理的丢弃比例，且分位样本量均衡。
本机实测：Alphalens 为什么装不上、装上后还要修什么
下面两条都是本机实际执行留下的记录（Python 3.11.9，2026-09-18）。原始输出保存在研究报告目录，可逐行核对。
# 记录一：安装主库失败
$ pip install alphalens
Downloading alphalens-0.4.0.tar.gz (24.0 MB)
Preparing metadata (pyproject.toml): finished with status 'error'
error: invalid command 'bdist_wheel'
error: metadata-generation-failed# 记录二：维护分支装成功，但默认依赖组合下导入仍可能失败
$ pip install alphalens-reloaded # 成功，装出 0.4.6
$ python -c "import alphalens"
ImportError: DLL load failed while importing _qn: 应用程序控制策略已阻止此文件。
# 调整依赖版本后又遇到：
ImportError: cannot import name '_lazywhere' from 'scipy._lib._util'| 记录 | 现象 | 根因 | 性质 | 处置 |
|---|---|---|---|---|
| 记录一 | 主库在元数据阶段直接失败 | 2020 年的构建脚本在新打包环境下找不到 wheel 命令 | 可复现的、与库年代相关的通病 | 改装维护分支 |
| 记录二（第 1 段） | 依赖里的编译模块被系统策略拦截，导入失败 | 本机 Windows 应用控制策略阻止了该 DLL | 本机环境特有，不是库缺陷 | 换依赖版本或调整本机策略；换机器一般不复现 |
| 记录二（第 2 段） | 换依赖版本后 scipy 找不到旧私有 API | 新版 scipy 移除了 _lazywhere，而旧版 statsmodels 仍在引用 | 依赖链版本错配，可复现 | 把 scipy 与 statsmodels 一起降到相互兼容的版本 |
| 记录二（处置结果） | 换成 statsmodels 0.14.4 + scipy 1.14.1 后 import alphalens 成功，随后完成了清洗、IC、分位收益、换手与出图 | 说明这类失败可以靠固定依赖版本绕过 | 本机可复现的成功组合 | 这一组合只在本机验证过；换环境需重新验证导入 |
| 共同点 | 两条都不是因子数据的问题 | 版本断层 | — | 先查环境再查数据，这也是本页排查顺序的由来 |
Alphalens 的依赖该怎么锁定：预防性配置
Alphalens 的问题几乎都能靠固定版本避免。下表给出可落地的做法与理由，不是通用最佳实践清单。
| 做法 | 为什么 | 怎么做 | 注意点 |
|---|---|---|---|
| 不用主库做新项目 | 主库依赖表无上限、构建脚本已失效 | 直接装维护分支，代码里仍 import alphalens | 历史研究若依赖主库特定行为，需先固定环境再复算 |
| 把 pandas 上限写进依赖文件 | 库声明只到 <3.0，越界会直接报错 | 在 requirements 里写 pandas>=1.5,<3.0 | 其他库可能要求更高 pandas，需一起评估 |
| scipy / statsmodels 成对锁定 | 新版 scipy 移除的私有 API 会被旧 statsmodels 引用 | 在锁定文件里同时钉住两者版本，并在本机验证导入 | 锁定后升级要重新跑一次导入验证 |
| 索引统一为无时区的规则交易日 | 时区与频率是两类高频报错的来源 | 入库前 tz_localize(None)，并对齐交易日历 | 跨市场数据要注意各自交易日历不同 |
| 绘图统一用非交互后端 | 无界面环境默认后端不可用 | 在脚本开头设置 Agg 后端 | 交互式调试时再切回默认后端 |
| 把库版本写进研究记录 | 累计收益等口径存在历史争议 | 在报告里记录包名、版本与参数组合 | 没有版本记录的图不可复现 |
Jupyter 与脚本环境为什么表现不同
同一份代码在 Notebook 里能跑、在脚本里报错，或者反过来，通常不是代码问题。下表把差异点列清。
| 差异点 | Jupyter | 脚本 / 命令行 | 对报错的影响 | 处理方式 |
|---|---|---|---|---|
| 绘图后端 | 通常是内联后端，直接显示 | 无界面环境没有可用后端 | 脚本里可能画不出图或直接异常 | 脚本开头 matplotlib.use("Agg") |
| 解释器 | 内核可能是另一个环境 | 当前终端的解释器 | 装到了 A 环境却用 B 环境运行，报 ModuleNotFoundError | 用 import sys; print(sys.executable) 核对 |
| 工作目录 | 通常是 Notebook 所在目录 | 取决于启动位置 | 相对路径读不到数据文件 | 统一用绝对路径或显式设置工作目录 |
| 变量残留 | 同一内核里多次执行会保留旧变量 | 每次运行都是干净进程 | Notebook 里「能跑」可能依赖了上一次的变量 | 定期重启内核并从顶部顺序执行 |
| 版本漂移 | 内核装的包可能在装库之后被升级 | 同 | 今天能跑、明天报错 | 把版本写进 requirements 并固定 |
| 显示层报错 | 富文本渲染可能吃掉异常 | 异常直接打到终端 | Notebook 里看不到完整堆栈 | 需要完整信息时用脚本复现一次 |
怎么把报错先定位到一类：可复制的诊断脚本
与其逐条猜报错，不如先把环境与数据的两类事实打印出来。下面这段脚本把上表与排查顺序里的检查点一次跑完（本机实测可执行）。
先打印环境三件套
解释器路径、Python 版本、关键依赖版本。预期：能一眼看出「装到了哪个环境、pandas 在不在支持区间内」。
再确认导入与包名
import alphalens并打印版本与文件路径。预期：区分「包没装」与「装了但导入失败」两种情况。最后检查数据三件事
索引是否可推断频率、有无重复 (date, asset)、因子与价格标的集合差。预期：把「环境问题」与「数据问题」分开，避免在错误的地方改参数。
import sys, importlib
print("python:", sys.version.split()[0], "|", sys.executable)
for m in ("pandas", "numpy", "scipy", "statsmodels"):
try:
mod = importlib.import_module(m)
print(m, getattr(mod, "__version__", "?"))
except Exception as e:
print(m, "IMPORT FAILED:", type(e).__name__, e)
try:
import alphalens
print("alphalens:", getattr(alphalens, "__version__", "?"), alphalens.__file__)
except Exception as e:
print("alphalens IMPORT FAILED:", type(e).__name__, e)
# data checks (fill in your own frames)
try:
import pandas as pd
print("infer_freq:", pd.infer_freq(prices.index))
print("dup index:", int(factor.index.duplicated().sum()))
print("assets only in factor:",
sorted(set(factor.index.get_level_values(1)) - set(prices.columns))[:10])
except NameError:
print("skip data checks: prices / factor not loaded")
Alphalens 报错常见问题
报错原文与 issue 编号全部来自官方仓库；本机实测记录仅代表本机环境，已逐条标注性质。
为什么我的报错不在上面这张表里？
这张表只收录仓库里真实存在、可核对的报错。你的报错如果不在表里，按「四步排查」顺序先确认包、解释器和 pandas 版本，再确认索引频率，最后看数据；绝大多数新报错都能归到这三类里。
升级 pandas 能不能解决所有问题？
不能，而且方向相反：主库的问题恰恰是「pandas 变新了、库没跟上」。正确顺序是先确认库版本支持到哪个 pandas，再决定用哪个 pandas，而不是先升 pandas。
维护分支是不是就没有报错了？
不是。它的 14 个 open issue 里有明确的未适配项（#46 关于 pandas 3.0），而且它同样把 scipy 写成了无上限。它只是把已知边界写清楚了，比主库可控。
可以直接改库源码绕过报错吗？
技术上可以，但不建议：升级依赖后改动会丢失，而且无法复现别人的结果。若必须临时改动，请在同一份研究记录里写清改了哪一行。
本机出现的 DLL 拦截是不是说明 Alphalens 不安全？
不是。那是本机 Windows 应用控制策略对某个依赖的编译模块的拦截，属于本机环境限制，与库的安全性、代码质量无关。换一台机器通常不会复现，页面已明确标注「本机环境特有」。
报错里出现中文市场相关的错误信息意味着什么？
说明索引或时区处理与库的假设不一致。issue #145 就是中国市场数据的时区问题。先把索引规整成无时区的规则交易日序列，再重跑，通常就能越过这一类问题。
遇到问题应该去哪问？
官方仓库的 issue 区仍然是主库问题的主要记录地，维护分支也有自己的 issue 区。提交前先搜一下是否已有相同报错——本页列出的 7 类报错都已有公开记录，可直接对照处理。
和免部署技能有关系吗？
没有已证实集成。这些报错都发生在你自己的 Python 环境里；客户端侧的技能无法替你修依赖，也不提供 Alphalens 运行环境。