如何快速上手 QuantStats 生成策略业绩报告（2026 版）

量化策略分析真正烦人的地方，往往不在公式本身：

• 绩效指标要一堆
• 图表要一堆
• 最后还想导出一个能分享的报告

QuantStats 的价值也正好在这里。它不负责帮你写策略，但能把“收益序列 -> 指标 -> 图表 -> 报告”这一整段重复劳动压缩掉。

这篇文章把旧文重新收了一遍。之前最容易把人带偏的地方有三个：

• 过早铺了太长的方法大全，反而让初学者抓不住主线
• 把外部数据源当成默认路径，但没有明确说清楚依赖条件
• 页面里用了实时 GitHub 组件，这会给静态构建引入不必要的不稳定因素

所以这次就不铺大表格了，先把最短路径跑通。

先跑一遍最短路径

如果你只是想先把 QuantStats 跑起来，可以按这个顺序来：

1. 安装 quantstats
2. import quantstats as qs
3. qs.extend_pandas()
4. 准备一份“日收益率 pd.Series”
5. 先跑 qs.plots.snapshot(...)
6. 再跑 qs.reports.html(...)

最小体验代码如下：

import quantstats as qs

qs.extend_pandas()

returns = qs.utils.download_returns("META")
benchmark = qs.utils.download_returns("SPY")

qs.plots.snapshot(returns, title="META Buy & Hold", show=True)
qs.reports.html(returns, benchmark=benchmark)

QuantStats 到底是什么

QuantStats 是一个 Python 分析库，主要做三件事：

• qs.stats
  • 计算指标
• qs.plots
  • 画图
• qs.reports
  • 生成报告

如果你把一条策略收益率序列喂给它，它就能帮你很快完成一轮常见绩效分析。

先把输入搞对

绝大多数 QuantStats 方法更在乎输入对不对，没那么在乎你策略讲得多高级。

先按这个标准看：

• 类型：pandas.Series
• 索引：DatetimeIndex
• 值：日收益率，不是价格

也就是说，直接喂收盘价不太合适。先做一遍 pct_change()，把 returns 准备好再给它。

一条当前更稳的上手路径

1. 安装

参考 QuantStats GitHub

!pip install quantstats --upgrade --no-cache-dir

如果你在 Notebook 环境里操作，这种写法就够用。

2. 初始化

import quantstats as qs

qs.extend_pandas()

extend_pandas() 的作用是把一些 QuantStats 能力挂到 pandas 对象上，后面你既可以用 qs.stats.xxx(...)，也能用更贴近 pandas 风格的写法。

3. 准备收益率序列

官方 README 最短的体验路径是直接下载收益率：

returns = qs.utils.download_returns("META")
benchmark = qs.utils.download_returns("SPY")

这条路径适合快速体验，但你需要知道它有两个现实前提：

• 依赖外部数据源
• 受网络、地区、数据接口可用性影响

所以在真正的研究或回测项目里，我更建议你优先使用自己已经清洗好的收益率序列。

例如，如果你已经有价格数据：

import pandas as pd

prices = pd.Series(
    [100, 101, 99, 104, 103],
    index=pd.to_datetime(
        ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-06", "2025-01-07"]
    ),
)

returns = prices.pct_change().dropna()

这类 returns 才是 QuantStats 最喜欢的输入。

先做两件最有价值的事

1. 用 snapshot 快速看整体状态

qs.plots.snapshot(returns, title="Strategy Snapshot", show=True)

这是我最建议先跑的第一张图，因为它能帮你快速看三件事：

• 累计收益走势
• 回撤情况
• 收益分布

在还没进入大而全报告前，这一步就足够帮你判断“这条策略有没有继续分析的必要”。

2. 用 html 生成可分享报告

如果你是自己研究、给同事看、或者想保留结果存档，那么 html 报告比只在 notebook 里看更实用。

qs.reports.html(returns, benchmark=benchmark)

如果你更喜欢在 Notebook 里直接展开一整套图表和指标，也可以用：

qs.reports.full(returns, benchmark)

两者都很常用，但我更建议初学者先把 html 报告跑通，因为它更接近真实的“输出物”。

如果你拿不到 download_returns 的数据怎么办

这不算 QuantStats 自己的问题，更多还是外部数据源的事。

如果 qs.utils.download_returns(...) 在你的环境里不可用，常见处理思路是：

• 换成你自己的 CSV / Parquet / 数据库结果
• 用其他数据接口先拿到价格，再自己算 pct_change()
• 最后把结果整理成 DatetimeIndex + pd.Series

对 QuantStats 来说，最重要的是“你给它的是一条合格的 returns 序列”，不是你从哪里拿到这条序列。

三个最常用的模块

qs.stats

适合你只想拿单个指标时用，比如：

qs.stats.sharpe(returns)
qs.stats.max_drawdown(returns)
qs.stats.cagr(returns)

qs.plots

适合探索式分析，比如：

qs.plots.snapshot(returns, show=True)
qs.plots.drawdown(returns, show=True)
qs.plots.monthly_heatmap(returns, show=True)

qs.reports

适合做最终产出，比如：

qs.reports.full(returns, benchmark)
qs.reports.html(returns, benchmark=benchmark)

这次我刻意删掉了什么

旧文里有很长的“方法大全”列表，但那不是初学者上手最需要的内容。

我这次刻意收掉了这些部分，原因很简单：

• 刚接触的人最需要的是跑通第一条路径
• 真要查全部方法，直接 dir(qs.stats) / dir(qs.plots) / dir(qs.reports) 更快
• 大段静态清单维护成本高，而且很容易随库版本变化而过时

如果你已经跑通基本流程，再去探索全量 API 会更自然。

一个更现实的工作流

如果你问我今天会怎么用 QuantStats，我会建议这样走：

1. 准备一条干净的日收益率序列
2. 先跑 snapshot
3. 再看几个核心指标，比如 Sharpe、CAGR、max drawdown
4. 最后生成一份 html 报告

没必要一开始就把所有 plots、stats、reports 方法全扫一遍。

总结

QuantStats 这类库最怕一上来就把函数表背一遍。先把收益率序列准备干净，再用 snapshot 和 html report 跑完第一轮分析，基本就能判断这套工具是不是适合你当前的研究流程。

参考资料

• QuantStats GitHub
• QuantStats on PyPI