polars-backtest

polars-backtest

Blazingly fast portfolio backtesting for Polars

• Blazingly fast, written in Rust with Arrow
• Native Polars integration with df.bt.backtest() namespace
• T+1 execution, stop loss, take profit, trailing stop
• Touched exit with intraday OHLC detection

Installation

pip install polars-backtest
# or
uv add polars-backtest

Quick Start

import polars as pl
import polars_backtest as pl_bt

# Long format data: one row per (date, symbol)
df = pl.DataFrame({
    "date": ["2024-01-01", "2024-01-01", "2024-01-02", "2024-01-02"],
    "symbol": ["AAPL", "GOOGL", "AAPL", "GOOGL"],
    "close": [100.0, 50.0, 102.0, 51.0],
    "weight": [0.6, 0.4, 0.6, 0.4],
})

# Run backtest
result = df.bt.backtest(trade_at_price="close", position="weight")

Visualization

Interactive, self-contained HTML report — no extra dependencies, works offline:

report = df.bt.backtest_with_report(position="weight", resample="M")

pl_bt.viz.show(report)                      # browser tab, or inline in notebooks
pl_bt.viz.save_html(report, "report.html")  # standalone shareable file
pl_bt.viz.report_data(report)               # JSON-safe payload for custom dashboards

Includes equity curve (benchmark overlay, log scale, range presets), drawdown, monthly return heatmap, trade return distribution, MAE scatter, and full stats. Light/dark mode follows the system.

Performance

300-day breakout strategy (~2000 stocks, 17 years daily data, 12M rows):

# Finlab
position = close >= close.rolling(300).max()
report = backtest.sim(position, resample="M")

# polars_backtest
df = df.with_columns(
    (pl.col("close") >= pl.col("close").rolling_max(300).over("symbol"))
    .alias("weight")
)
report = df.bt.backtest_with_report(position="weight", resample="M")

	Finlab	polars_backtest
Time	3.7s	244ms
Speedup	1x	15x faster

just bench  # Run benchmarks

Features

• Rust Core - Pure Rust implementation with Arrow
• Native Polars - Works with long format DataFrames, supports Polars expressions
• T+1 Execution - Realistic trading simulation
• Risk Management - Stop loss, take profit, trailing stop, touched exit (OHLC)
• Flexible Rebalancing - Daily, weekly, monthly, or on position change
• Claude Code Skill - AI-powered assistance for backtesting

Claude Code Integration

Get AI-powered assistance for writing and analyzing backtests.

Install the Skill

# 1. Add the marketplace
/plugin marketplace add Yvictor/polars_backtest_extension

# 2. Install the plugin
/plugin install polars-backtest@polars-backtest-marketplace

After installation, Claude Code can help you:

• Write backtest strategies using Polars expressions
• Understand all parameters and their effects
• Analyze results with get_metrics(), get_stats(), etc.
• Debug and optimize your trading strategies

---

Usage

Basic Backtest

import polars_backtest as pl_bt

# Function API
result = pl_bt.backtest(df, trade_at_price="close", position="weight")

# DataFrame namespace
result = df.bt.backtest(trade_at_price="close", position="weight")

With Expressions

result = df.bt.backtest(
    trade_at_price="close",
    position=pl.col("signal").cast(pl.Float64),
    resample="M",
)

Full Report with Trades

report = pl_bt.backtest_with_report(df, trade_at_price="adj_close", resample="M")
report

BacktestReport(
  creturn_len=4219,
  trades_count=6381,
  total_return=8761.03%,
  cagr=29.85%,
  max_drawdown=-35.21%,
  sharpe=1.13,
  win_ratio=46.33%
)

report.get_stats()  # or report.stats