QuantStats · Installation
QuantStats安装教程：pip/conda 两种方式与依赖清单
这个库支持 pip 与 conda 两种官方安装方式，要求 Python≥3.10，并依赖 pandas、numpy、scipy、matplotlib、seaborn、tabulate、yfinance 等。安装后 import quantstats as qs 即可开始使用；本页补齐官方 README 没细讲的国内网络、装错环境、装完怎么验证三类问题。
quantstats
-c ranaroussi
隔离环境
两条官方安装路径与虚拟环境示意；基于官方 README，非官方路线图。
QuantStats 安装方式有哪些？该选哪一种
官方 README 提供 pip 与 conda 两条主路径；下表同时列出虚拟环境、源码、内网离线、版本锁定等常见工程变体，覆盖不同网络与团队环境。
| 方式 | 命令 | 适用场景 | 注意点 |
|---|---|---|---|
| pip（官方主路径） | pip install quantstats --upgrade --no-cache-dir | 最常用，个人电脑与服务器均适用；配合 venv 使用更干净 | --no-cache-dir 避免旧缓存干扰升级；命令里要确认 pip 属于你要用的那个解释器 |
| conda（官方主路径） | conda install -c ranaroussi quantstats | 已在用 conda/Anaconda 管理 Python 与科学计算依赖的用户 | 依赖 ranaroussi 频道可用性与同步速度；频道未命中时会提示找不到包 |
| 虚拟环境 + pip（推荐组合） | python -m venv venv 激活后再执行上面的 pip 命令 | 一个机器上跑多个项目、版本互不干扰；也便于整目录删除回滚 | 每次使用前必须先激活，否则会退回系统 Python 并报「找不到包」 |
| 源码安装（变体） | pip install git+https://github.com/ranaroussi/quantstats | 需要开发版或尚未发版修复的场景 | 不是 README 主路径；结果随仓库分支变化，可复现性差，需记录 commit |
| 内网 / 离线安装 | 在有网环境下载 wheel，再 pip install 本地文件 | 无外网的准生产/隔离环境 | 必须同时准备全部依赖 wheel，缺一个就失败；具体可用性以 PyPI 提供为准 |
| 固定版本复现 | 装完后 pip freeze > requirements.txt 锁定版本 | 研究报告要复现、多人协作对齐环境 | 锁定后升级要显式操作；依赖最低版本以官方 README 为准 |
| 国内镜像加速 | 给 pip 加 -i 指定国内镜像 | 中国大陆网络下载 pip 包慢或超时 | 镜像同步有延迟，装不到最新版属正常现象，详见下一节 |
pip 安装 quantstats 怎么一步步做
按「确认环境 → 隔离 → 安装 → 验证 → 试算 → 存证」六步落地，每一步都给出可核对的预期输出。
1. 确认 Python 版本：python --version 需输出 ≥ 3.10。预期输出形如 Python 3.11.9；若低于 3.10，依赖解析阶段就会失败，先升级 Python 再继续。多版本并存时用 py -0（Windows）或 which -a python3（macOS/Linux）确认当前用的是哪一个。
2. 创建并激活虚拟环境（推荐）：python -m venv venv，Windows 激活 venv\Scripts\activate、macOS/Linux 执行 source venv/bin/activate。预期表现是命令行提示符前出现 (venv)；没有出现就说明没激活成功，后面的安装会落到别处。
3. 安装：pip install <包名> --upgrade --no-cache-dir。pip 会顺带解析并安装 pandas/numpy/scipy/matplotlib/seaborn/tabulate/yfinance 等依赖；预期输出末尾出现 Successfully installed quantstats-x.y.z ...。若这一步报依赖冲突，直接跳到本页「安装与环境排查」表。
4. 验证可导入并打印版本：python -c "import quantstats as qs; print(qs.__version__)"。预期输出一行版本号且无任何 traceback；报 ModuleNotFoundError 说明装到了另一个解释器，回到第 2 步检查环境。
5. 确认安装位置没装错：pip show quantstats，预期 Location: 指向当前 venv 的 site-packages 目录。这一条是排查「明明装了却 import 不到」最有效的一步，比反复重装更快定位。
6. 用自备收益序列试算一个指标：python -c "import quantstats as qs; import pandas as pd; r=pd.Series([0.01,-0.02,0.03]); print(qs.stats.sharpe(r)); qs.extend_pandas(); print(r.sharpe())"。预期输出两个数值。这个例子不依赖网络，用来验证核心 stats 模块可用（示例数字仅用于验证安装，不构成任何绩效结论）。
quantstats 依赖哪些库？缺了会怎样
依据官方 README Requirements 整理（版本为最低要求），最后一列说明「不满足会怎样」。
| 依赖 | 最低版本 | 用途 | 不满足会怎样 |
|---|---|---|---|
| Python | 3.10+ | 运行时；全部代码需在 3.10 及以上版本运行 | pip 直接拒绝安装或解析失败 |
| pandas | 1.5.0 | 收益序列核心数据结构（Series/DataFrame），qs.extend_pandas() 依托它 | import 阶段即报错 |
| numpy | 1.24.0 | 底层数值计算（均值、标准差、收益复合等向量化运算） | 部分指标计算抛异常 |
| scipy | 1.11.0 | 统计分布、VaR/CVaR 等风险指标的统计计算 | 风险指标不可用 |
| matplotlib | 3.7.0 | plots 模块所有绩效图（净值/回撤/月度热力图等）的绘图引擎 | 画图与 HTML 报告中的图表缺失 |
| seaborn | 0.13.0 | 月度热力图等统计图的样式封装 | 热力图类图缺失 |
| tabulate | 0.9.0 | 把指标结果渲染成对齐的文本表格（终端输出） | 终端指标表打印异常 |
| yfinance | 0.2.40 | qs.utils.download_returns() 拉取美股等行情数据 | 只剩「自备收益序列」一条路 |
| plotly（可选） | 5.0.0 | 仅 plots.to_plotly() 把静态图转交互图时需要 | 仅该函数报错，其他功能不受影响 |
| 浏览器（查看报告） | 任意现代浏览器 | 打开生成的 HTML 绩效报告 | 报告文件已生成但打不开 |
国内网络下装不上、拉不到数据怎么处理
安装慢和数据拉不到是两件不同的事：前者靠镜像解决，后者与第三方数据源有关，官方文档都没细讲。
| 环节 | 典型现象 | 可用做法 | 注意点 |
|---|---|---|---|
| pip 下载包 | 下载缓慢、Read timed out，装不上或反复重试 | 临时指定镜像：pip install quantstats -i https://pypi.tuna.tsinghua.edu.cn/simple | 只影响包下载来源，不改库的功能 |
| pip 长期配置 | 每次都手敲 -i 太麻烦 | 写进配置：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple | 镜像同步有延迟，可能出现「装不到最新版」 |
| conda 下载包 | conda 解析慢或超时 | 按国内 Anaconda 镜像站公告的配置方式添加镜像频道 | 具体频道地址与配置命令以镜像站公告为准，不使用来路不明的频道 |
| 拉取行情数据 | qs.utils.download_returns('META') 超时、返回空或报错 | 改用自备收益序列（本地 CSV 或 DataFrame）直接传入 | 该函数依赖 yfinance 与海外行情服务，能否连通视网络环境而定，以官方文档与实际网络为准 |
| 下载超时后反复重装 | 反复 Read timed out，重试多次仍失败 | 加长超时并指定镜像：pip install quantstats -i <镜像地址> --default-timeout=60 | 只缓解网络抖动；若被公司网络策略拦截，仍需网络侧放行域名 |
| 无外网的服务器 / 隔离环境 | PyPI 与镜像都不可达，pip 无法解析 | 在有网机器执行 pip download <包名> -d wheels 下载 wheel，再拷贝到目标机离线安装 | 依赖需一次性备齐，缺一个 wheel 整体就装不完 |
| 走公司代理的网络 | 报 SSL 错误、连接被重置 | 给 pip 显式指定代理：pip install --proxy http://主机:端口 quantstats | 代理地址与放行域名由网络管理员提供，不要用来路不明的代理 |
镜像安装的标准写法：pip install <包名> -i https://pypi.tuna.tsinghua.edu.cn/simple —— 一次性加速，不影响其他项目。预期输出：与正常 pip 安装同样的 Successfully installed 结尾，区别只是下载源变成镜像站。
装不上时先分区定位：能解析到包但下载慢 → 网络/镜像问题；连包名都解析不到 → 包名拼写或镜像未同步。分开判断可以避免把「拼错包名」当成网络故障反复换镜像。
数据拉不到时不要怀疑安装：download_returns 走的是第三方行情服务，与库本身是否装好无关；先用自备序列跑通指标，再单独排查网络，能少绕很多弯路。
怎么确认 quantstats 真的装对了
「装完没报错」不等于「装对了」：装到别的解释器、装进系统环境、依赖版本过旧，都会在后面才暴露。
验证一：能不能导入 —— python -c "import <包名> as qs; print(qs.__version__)"。预期输出：一行版本号，无 traceback。这是最基本的通过/不通过判据。
验证二：装到了哪个位置 —— pip show <包名>。预期输出：Location: 指向当前 venv 的 site-packages。若指向系统目录或另一个 Python 安装，说明环境选错了。
验证三：核心计算能不能跑 —— 用自备序列算一个指标：python -c "import quantstats as qs; import pandas as pd; r=pd.Series([0.01,-0.02,0.03,0.015]); print(qs.stats.sharpe(r))"。预期输出：一个数值。不依赖网络，能排除数据源干扰。
验证四：pandas 扩展是否生效 —— qs.extend_pandas() 之后可以直接写 r.sharpe()（官方 README 的 monkey-patching 用法）。预期输出：与验证三一致的数值。若报 AttributeError，通常是忘记先调用 extend_pandas()。
| 验证项 | 通过表现 | 不通过说明什么 |
|---|---|---|
| import + 版本号 | 打印出版本号 | 没装上，或解释器不是安装时用的那个 |
| pip show 的 Location | 指向当前虚拟环境的 site-packages | 装到了系统环境或另一个 Python |
| 指标计算 | 返回数值 | 依赖版本过旧或部分依赖缺失 |
| 绘图能力（可选） | 能出图 | matplotlib/seaborn 未装好，只影响画图 |
| conda 环境里的包列表 | conda list 中能看到 quantstats | 列表里没有但 import 正常，说明是用 pip 装进该环境的，属正常现象 |
| 端到端生成一次 HTML 报告 | 生成 HTML 文件且能在浏览器打开 | 失败先看输出目录权限与绘图依赖，多数不是安装本身的问题 |
| 升级后的版本号 | 版本号变化，或提示已是最新 | 刚升级过版本号却不变，多半升级到了另一个 Python 环境 |
安装报错时怎么排查？常见现象对照
按「现象 → 可能原因 → 处理方式」列出实际最常遇到的八类问题。
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| ModuleNotFoundError: No module named 'quantstats' | 未安装，或当前解释器不是安装所在环境（venv 未激活） | 先激活对应 venv，再 pip show <包名> 确认；确实缺失就重新安装 |
| 提示不满足 Python 版本要求 | 解释器低于 3.10，不满足官方 Requirements | 升级解释器后用新版本重建 venv；不要在原环境硬改 |
| pip 报依赖冲突（conflicting dependencies） | 已有 pandas/numpy 版本与新库要求不兼容 | 新建干净 venv，用 --no-cache-dir 重装，不要在原环境硬凑版本 |
| 装了两次还是 import 不到 | 机器上多个 Python（系统自带 + conda + pyenv），pip 与 python 不是同一个 | 统一用 python -m pip install ... 形式安装，避免 pip 指向错解释器 |
| download_returns 超时或返回空 | 第三方行情服务网络不通或限流 | 换成本地 CSV/DataFrame 自备收益序列传入；网络问题需单独排查 |
| numpy/scipy 安装时报编译错误 | 平台没有匹配 wheel，回退到源码编译且缺少工具链 | 升级 pip 后重试（优先取 wheel）；仍失败则换 Python 版本或改用 conda 生态 |
| 图里中文变方块 | matplotlib 默认字体不含中文，且未指定中文字体 | 在脚本里显式设置可用中文字体后再绘图；属绘图环境问题，非安装失败 |
| pip 与 conda 混装后 import 报别的错 | 同一环境被两个包管理器反复改写依赖 | 一个环境只用一个包管理器；最省事的做法是直接重建环境 |
Windows 上装 quantstats 最容易卡在哪几步？
官方 README 只给两条安装命令，Windows 上真正的坑在「装到哪个解释器、用哪个终端激活环境、路径写在哪」。下表把每一步的判据与可直接执行的处置放在一起。
| 卡点 | Windows 上的具体表现 | 可直接执行的处置 |
|---|---|---|
| 装了却找不到模块 | 安装提示成功，运行脚本报 ModuleNotFoundError；where python 会列出多条路径 | 改用 python -m pip install <包名> --upgrade，让 pip 绑定当前 python；再用 where python 确认脚本用的是哪一个 |
| 装进了另一个 Python | pip show <包名> 的 Location 指向 AppData\Local\Programs\Python\...，而你实际在用 conda 环境 | 用目标环境的解释器执行安装（<该环境 python 路径> -m pip install quantstats）；py -0 可列出本机全部解释器 |
| 虚拟环境没激活就装 | 命令行提示符前没有 (venv)，包被装进系统 Python | cmd 执行 venv\Scripts\activate，PowerShell 执行 venv\Scripts\Activate.ps1，看到 (venv) 再安装 |
| PowerShell 禁止运行激活脚本 | 报「无法加载文件 ...Activate.ps1，因为在此系统上禁止运行脚本」 | 只放开当前会话：Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass，然后重新激活；不需要改全局策略 |
| 绘图第一次很慢、中文变方块 | 首次 import matplotlib 卡十几秒；图上的中文标签显示为方框 | 首次变慢是构建字体缓存，属正常；中文需在脚本里显式指定本机已安装的中文字体后再绘图 |
| 路径过长或含特殊字符 | 安装或生成报告时报文件名过长、目标目录不存在 | 虚拟环境建在短路径（如 D:\py\qs）；报告输出到已存在且可写的目录 |
| 想升级到新版 | 不确定该用哪条命令，或升级后版本号没变 | 升级用 python -m pip install --upgrade <包名>；版本号没变说明升级到了另一个环境 |
| 想彻底卸载重来 | 卸载后仍能 import，怀疑没删干净 | 先 python -m pip uninstall <包名>；虚拟环境里的更彻底做法是直接删掉整个环境目录再重建 |
免费吗？许可、版本与质量边界
安装前最常被问到的几个问题，官方 README 分散在不同位置，这里集中说明。
| 问题 | 结论 | 边界与依据 |
|---|---|---|
| 要付费吗？ | 不用，是本机安装的开源库，pip/conda 免费获取 | 以仓库 LICENSE 为准；第三方数据源可能有自己的限流与条款 |
| 能商用吗？ | 可以，许可为 Apache-2.0，允许使用、修改与分发 | 需保留版权与许可声明；具体条款以仓库 LICENSE 原文为准 |
| 有中文文档吗？ | 官方 README 为英文，未见官方中文文档 | 第三方中文资料可能存在，但不属官方；以官方仓库与文档为准 |
| 包含行情数据吗？ | 不包含。它是分析工具，数据由 yfinance 拉取或由你自备 | 数据质量、复权口径、覆盖市场取决于数据来源，不是库的职责 |
| 规模与活跃度 | GitHub 约 7.6k Star（2026-09-10 采集），持续更新 | Star 数随时间变化，仅作参考，不构成质量评价 |
| 能给我投资建议吗？ | 不能。它只做历史收益序列的统计与可视化 | 输出仅供研究，不构成投资建议，也不保证未来表现 |
QuantStats 装法怎么选？什么场景用哪种装法
把「场景 → 推荐做法 → 理由」对齐，避免为了装一个库把环境搞乱。
| 你的场景 | 推荐做法 | 理由 |
|---|---|---|
| 个人电脑第一次尝鲜 | venv + pip 安装 | 不污染系统 Python，卸载只需删目录，试错成本最低 |
| 已经在用 conda 做量化/科研 | conda 频道安装 | 与现有依赖体系一致，避免再引入一套包管理逻辑 |
| 服务器/内网无外网 | 有网机器下载 wheel 后离线安装 | 隔离环境的唯一可行路径，前提是一次性备齐全部依赖 wheel |
| 研究报告需要可复现 | 虚拟环境 + 锁定依赖版本 | 半年前能跑通的结论，今天还能跑通；浮动版本做不到 |
| 需要未发布修复或开发版 | 源码安装并记录 commit | 能拿到最新改动，但要接受结果随分支变动、可复现性差 |
| CI / 容器环境跑批 | 镜像构建阶段 pip 安装并固定版本 | 构建即固化环境；官方未提供官方容器镜像，以仓库与官方文档为准 |
| 完全不想碰命令行与环境 | 改用免部署的量化研究 Skill 路线 | 放弃对代码与环境的控制权，换取零维护；能力边界由该路线决定 |
QuantStats 安装常见问题有哪些
这个库需要付费吗？
不需要。它是 Apache-2.0 开源库，pip/conda 免费安装，允许商用并保留版权与许可声明；但拉取行情数据的第三方源（如 yfinance 走的行情服务）有自己的限流与条款，具体以仓库 LICENSE 与官方 README 为准。
必须用 conda 吗？
不必。pip 和 conda 二选一即可，官方 README 两者都支持；conda 的优势是与现有科学计算环境统一，pip 的优势是更轻、更通用。具体以官方 README 的 Installation 段落为准。
pip 和 conda 能混用吗？
不建议。同一环境混用容易出现依赖版本冲突，典型表现是「装的时候成功、用的时候报错」；建议统一用一种包管理器并配合独立环境。官方未对混用作兼容承诺，以官方安装说明为准。
安装后怎么确认成功？
两步：python -c "import <包名> as qs; print(qs.__version__)" 能打印版本号；pip show <包名> 的 Location 指向当前虚拟环境。两步都过说明装对了环境，只过第一步则可能装到了别的解释器。
国内网络装不上怎么办？
先区分是「下载慢」还是「解析不到包」：前者用 pip install <包名> -i https://pypi.tuna.tsinghua.edu.cn/simple 走镜像；后者多为包名拼写或镜像同步延迟。镜像可用性随时间变化，以镜像站公告为准。
Windows 能装吗？
可以。官方 README 未对操作系统设限，pip/conda 在 Windows、macOS、Linux 均有对应包，前提是 Python≥3.10 且依赖能解析到匹配 wheel；遇到需要本地编译的依赖时，优先升级 pip 或改用 conda。以官方 README 与实际解析结果为准。
我想免部署、不装 Python 环境怎么办？
可了解本机量化 Skill 的免部署研究路线（如 quant-analyst 量化分析、akshare-finance 财经数据），装好客户端后用一句话发起任务即可。需要注意这类路线与 QuantStats 无已证实集成，数据源、市场覆盖与输出形式各不相同，选择前请核对其能力边界。