QuantStats

0.0.81 · active · verified Thu Apr 16

QuantStats is a Python library for portfolio analytics that enables quantitative analysts and portfolio managers to gain in-depth insights into their investment performance and risk metrics. It provides modules for calculating various statistics, generating plots, and creating comprehensive HTML reports. The library is actively maintained with frequent updates, with the current version being 0.0.81.

Common errors

```
ImportError: cannot import name 'stats' from partially initialized module 'quantstats' (most likely due to a circular import)
```
cause This error typically indicates a circular dependency issue during module loading, often triggered when `quantstats` itself tries to import a submodule that, in turn, attempts to import a parent module before it's fully initialized.

fix This was a known bug in `quantstats` versions 0.0.78 and 0.0.79. Upgrade your `quantstats` package to version 0.0.80 or newer: `pip install quantstats --upgrade`.
```
NameError: name 'dd_get_stats' is not defined
```
cause This error occurs specifically when attempting to generate a full report using `qs.reports.full()` in certain versions of `quantstats` due to a mistyped internal function name.

fix This bug was fixed in `quantstats` version 0.0.81. Upgrade your package: `pip install quantstats --upgrade`.
```
FutureWarning: The default fill_method='pad' in Series.pct_change is deprecated and will be removed in a future version.
```
cause This `FutureWarning` originates from pandas, indicating that `quantstats` functions using `pct_change()` with the implicit default `fill_method='pad'` are relying on deprecated behavior.

fix This warning was addressed in `quantstats` version 0.0.78. Upgrade your `quantstats` package to this version or newer: `pip install quantstats --upgrade`.
```
FutureWarning: The '1M' freq alias is deprecated and will be removed in a future version, use 'M' instead.
```
cause This `FutureWarning` is from pandas, indicating that `quantstats` or user code is using outdated frequency aliases (e.g., '1M') that are no longer recommended and will be removed.

fix This warning was resolved in `quantstats` version 0.0.75 by updating internal usage to modern pandas frequency aliases (e.g., '1ME'). Upgrade your package: `pip install quantstats --upgrade`.

Warnings

breaking Circular import errors (e.g., 'ImportError: cannot import name "stats" from partially initialized module "quantstats"') were prevalent in versions 0.0.78 and 0.0.79.
Fix: Upgrade to version 0.0.80 or later. These issues were resolved by implementing lazy imports.
breaking A `NameError: name 'dd_get_stats' is not defined` occurred in `reports.full()` due to a typo in versions 0.0.78 and 0.0.79, preventing full report generation.
Fix: Upgrade to version 0.0.81 or later. The typo was corrected in this release.
deprecated Older versions of QuantStats might trigger `FutureWarning`s from pandas regarding the deprecated `fill_method` in `Series.pct_change()`. This could clutter console output.
Fix: Upgrade to version 0.0.78 or later, where `pct_change()` calls were updated to use `fill_method=None` or equivalent, suppressing the warning.
deprecated Pandas `FutureWarning`s related to deprecated frequency aliases (e.g., '1M' for monthly) were common in older versions, especially with pandas 2.0+.
Fix: Upgrade to version 0.0.75 or later. The library was updated to use modern pandas frequency aliases (e.g., '1ME' for month end) for compatibility.

Install

pip install quantstats Install QuantStats

Imports

quantstats
```
import quantstats as qs
```
Standard import alias for brevity.
extend_pandas
```
qs.extend_pandas()
```
Extends pandas DataFrames/Series with QuantStats metrics and plotting methods, allowing method chaining (e.g., `df.sharpe()`). Should be called after importing quantstats.

Quickstart

This quickstart demonstrates how to import QuantStats, extend pandas DataFrames for easy access to metrics, download historical stock data using `yfinance`, calculate a basic performance metric like the Sharpe Ratio, and generate a comprehensive HTML tearsheet comparing a stock's performance against a benchmark.

import quantstats as qs
import yfinance as yf
import pandas as pd

# Extend pandas functionality with QuantStats methods
qs.extend_pandas()

# Download daily returns for a stock using yfinance
ticker = 'AAPL'
stock_data = yf.download(ticker, start='2020-01-01', end='2023-12-31')
returns = stock_data['Adj Close'].pct_change().dropna()

# Optionally, download benchmark returns
benchmark_ticker = 'SPY'
benchmark_data = yf.download(benchmark_ticker, start='2020-01-01', end='2023-12-31')
benchmark_returns = benchmark_data['Adj Close'].pct_change().dropna()

# Calculate and print Sharpe Ratio
sharpe_ratio = returns.sharpe()
print(f"Sharpe Ratio for {ticker}: {sharpe_ratio:.4f}")

# Generate a full HTML report (opens in browser by default)
# Ensure you have matplotlib and seaborn installed for plots
qs.reports.html(returns, benchmark=benchmark_returns, title=f'{ticker} vs {benchmark_ticker} Performance', output='quantstats_report.html')

view raw JSON →