7.6k stars · Apache-2.0 · v0.0.81 (2026-01-13) · Track this in Rising ↗
Portfolio tearsheets from a returns series — the monthly-returns heatmap that tests the 2%-a-month claim, under a licence he can ship.
Radar check
What we found when we opened it. Every bar is one fact, with its date.
Last code pushed 27 Sep 2026, 30 days before this check.
Latest release v0.0.86 on 27 Sep 2026.
Public since May 2019, a little over 7 years.
7,757 stars and 1,265 forks.
9 commits and 10 new issues in the last 90 days.
36 contributors. No pull requests merged in 90 days; changes go in directly.
No security policy file says how to report a problem. No published security advisories.
How the bars are scored
- Alive. Days since the last code push: a week or less 100, a month 90, three months 70, six months 50, a year 30, eighteen months 15, older 0.
- Releases. Age of the latest GitHub release, on a similar scale; no bar when the project publishes no releases.
- Maturity. Age of the project: eight years 100, five 90, three 70, two 55, one 40, six months 25, younger 10.
- Adoption. Stars on a log scale: 100,000 stars is 100, 10,000 is 80, 1,000 is 60, 100 is 40.
- Activity. Commits in the last 90 days: 300 or more 100, 100 85, 30 65, 10 45, any 25.
- Community. People who have contributed: 100 or more 100, 30 80, 10 60, 5 40, 2 25, one 10.
- Security. A published security policy 80, none 40; published advisories are listed, not scored.
Checked by Repo Radar on 27 Oct 2026 from the repository on GitHub. Covered in Edition 4.
▶Repo detailsthe review · specs · pros & cons · install
What it does
It takes a series of returns and produces a complete set of portfolio statistics. Sharpe and Sortino ratios, maximum drawdown, win rate, rolling volatility and value at risk are all included. It draws a monthly-returns grid, which shows each month of each year as a coloured cell. Everything is written into a single self-contained HTML file that needs nothing else to open. A strategy can be compared against a benchmark series in the same report. It works with pandas series, which is the standard Python way of holding a column of dated numbers. It does not run a backtest and does not produce the returns. Something else has to generate them first.
Why it matters
Who it suits. Anyone judging a trading or investing strategy whose target is stated as a monthly figure. The monthly grid answers that question directly: it shows whether a steady monthly number is a real pattern, or one good quarter carrying eleven mediocre months behind it. Skip it if there is no returns series yet, because this is the reporting step and not the research step.
Verdict. Worth ten minutes, and the licence is the sharper reason to use it. Apache-2.0 means the report can sit inside commercial software, which is not true of the popular backtesters: backtesting.py is AGPL-3.0 and vectorbt carries a Commons Clause. So build the report a customer will see on this, and keep a restrictively licensed backtester for private research. Two cautions. The version number is still 0.0.86 after years of releases, which signals a low-ceremony project, and some of its plotting dependencies are fussy about versions. And beautiful statistics on an over-fitted strategy are still an over-fitted strategy; this will flatter a bad result convincingly.
Summary (Key Points)from the README
Key features
- Three modules: `quantstats.stats` calculates metrics such as Sharpe ratio, win rate and volatility, `quantstats.plots` visualizes performance, drawdowns, rolling statistics and monthly returns, and `quantstats.reports` builds metric reports, batch plots and tearsheets.
- Monte Carlo simulations: Built-in probabilistic risk analysis, with a separate full Monte Carlo documentation page.
- HTML tearsheets: `qs.reports.html(...)` generates a complete report that can be saved as an HTML file.
- Basic and full reports: `qs.reports.metrics`, `qs.reports.plots`, `qs.reports.basic` and `qs.reports.full` offer metrics-only, plots-only, or combined views, with `mode='basic'` or `mode='full'` for the first two.
- Return-series metrics: Win rate, consecutive wins and losses, payoff ratio and profit factor are computed on daily, weekly or monthly return periods.
- Stock data: Lists yfinance as a requirement, which suggests it can pull price data for analysis (the README's quick start example is not shown in the text).
- Optional Plotly output: `plots.to_plotly()` is available when plotly is installed.
- Built-in help: Python's `help` function reveals optional parameters for each method, since the full documentation is still pending.
Ways to install
| Platform or method | What it needs | Effort |
|---|---|---|
| pip | Python >= 3.10 and the listed dependencies (pandas, numpy, scipy, matplotlib, seaborn, tabulate, yfinance; plotly optional) | Not stated in README |
| conda | Python >= 3.10 and the listed dependencies (pandas, numpy, scipy, matplotlib, seaborn, tabulate, yfinance; plotly optional) | Not stated in README |
Important
- Period-based, not trade-based: Win rate and related figures count return periods, so a multi-day trade can show several "wins" and "losses" that differ from trade-level statistics. Discretionary traders with multi-day trades should keep this in mind.
- Tearsheet count mismatch: The README says there are 7 report tearsheets but lists only five.
- Documentation gap: Full documentation is marked "coming soon," so the help function is the main reference for optional parameters.
- Seaborn known issue: The monthly returns heatmap still displays even when saved with `savefig={...}`.
- Young library: The author describes it as new and asks users to report bugs via issues.
- Python version: It requires Python 3.10 or later, and several dependencies have minimum versions.
Written by an AI model from the project’s README; not part of the review, and it can be wrong.
- Apache-2.0, so unlike the popular backtesters it is safe inside commercial software
- The monthly-returns grid turns a monthly target into a picture you can read at a glance
- One call produces a complete HTML report that can be served or sent as a file
- It reports; it does not backtest, so something else must produce the returns
- Version 0.0.86 after years of releases, and some plotting dependencies are fussy
- It will present an over-fitted strategy beautifully and convincingly
python3 -m venv venv source venv/bin/activate pip install quantstats
