OpenBacktesting

Historical backtesting in Python, from strategy rules to inspectable results.

English · 简体中文 · Español · Português (Brasil) · Français · Deutsch · Italiano · हिन्दी

Write bar-by-bar strategies, evaluate them on historical market data, and inspect orders, trades, equity, and risk statistics. OpenBacktesting is a standalone Python package with indicators, parameter optimization, Portfolio reports, and plotting-data export.

Python 3.12–3.14 · Version 0.2.1 · Distribution and import: openbacktesting

Quick start · Manual · Examples · Local development · Contribute · Report an issue

Top sponsor — Pineify

Pineify is OpenBacktesting's top paid sponsor. Its financial support helps fund this project.

Pineify is an AI trading toolkit for building indicators and strategies across multiple platforms. It brings together Pine Script AI, a Finance Agent, AI stock picking, market screening, chart analysis, and MCP tools. Explore Pineify →

What you can do

• Build strategies: use a bar-by-bar lifecycle, typed inputs, built-in indicators, and composable helpers.
• Inspect execution: examine orders, fills, position sizing, fees, closed trades, and open lots.
• Analyze results: read pandas statistics, equity curves, and immutable Portfolio reports for each run.
• Compare parameters: run grid searches or optional SAMBO optimization, save experiment results, and export plotting data for your own renderer.

Quick start

Install the Python framework from PyPI into a Python 3.12–3.14 environment:

python -m pip install openbacktesting==0.2.1

For the repository examples and local development, use a source checkout:

Install uv and use Python >=3.12,<3.15. From a terminal:

git clone https://github.com/lucidcog/openbacktesting.git
cd openbacktesting
uv sync --locked
uv run --locked python examples/advanced/native_run.py

The example uses bundled GOOG historical data; no market-data download is required. It prints return, trade count, maximum drawdown, and result tables. See your first backtest for a walkthrough.

To install the checked-out source into an existing Python environment instead:

python -m pip install .

The base dependencies are NumPy, pandas, and pandas-ta-classic==0.8.32. For SAMBO optimization, use python -m pip install '.[optimize]' or uv sync --locked --extra optimize. These are source-installation instructions; they do not assume a PyPI release. Build and distribution details.

Optional Studio

Use OpenBacktesting Studio to edit local strategy files, configure inputs, inspect charts and reports, and compare parameter experiments in your browser. It is a separate Python distribution; framework-only users do not install its web assets. The illustrated guide covers installation, launching Studio, and running your first strategy.

python -m pip install openbacktesting-studio==0.1.0
openbacktesting-studio /path/to/strategies

Studio installs its compatible core dependency automatically and includes the compiled web interface. End users do not need Node.js or npm.

Minimal backtest

Save this as quickstart.py in the repository root and run uv run --locked python quickstart.py:

from openbacktesting import Backtest, Strategy
from openbacktesting.test import GOOG


class BuyAndHold(Strategy):
    def init(self):
        pass

    def next(self):
        if self.bar_index == 0:
            self.buy(qty=1)


result = Backtest(GOOG, BuyAndHold, end_policy="close_at_last_close").run()
print(result[["Return [%]", "# Trades", "Max. Drawdown [%]"]])

This strategy requests one unit on the first bar. Default execution occurs at the next bar's open; close_at_last_close closes the remaining position at the final close.

run() returns a pandas Series. Use result["_trades"] for trades and result["_equity_curve"] for equity history. See the results guide for the full field list and Portfolio export; underscore-prefixed fields are native diagnostics, not a stable cross-language contract.

Documentation

Manual

The detailed manual and examples are currently in English.

The online manual includes sidebar navigation, page outlines, and full-text search. To preview documentation changes locally:

uv run --locked --group docs mkdocs serve

Open http://127.0.0.1:8000. The server reloads when documentation changes. Build a static site with bash scripts/build_docs.sh; the output is in build/docs/. See Cloudflare Pages deployment for the build settings.

Topic	Reference
Getting started	First backtest · Example index
Strategies and data	Strategy lifecycle · Market data · Strategy API · Backtest API
Orders and positions	Order, Position, and Trade
Indicators	Indicator catalog
Execution and optimization	Running strategies · Parameter experiments
Results and plotting	Results and Portfolio · Plotting-data export
Development and contributions	Local development · Contribution guide · Current limitations

Scope and compatibility

• The trading model is single asset, single settlement currency. Portfolio reports describe one run; they are not multi-asset portfolio accounts.
• The core package provides computation and plotting data. It includes no chart renderer, live-trading engine, code sandbox, or Pine Script converter, and does not promise Pine-equivalent semantics. Run only trusted strategy code.
• Windows support and full Pine comparisons have not been validated. See current limitations for execution and market-model boundaries.

The distribution and import name are both openbacktesting; there are no legacy-name entry points. Old module-path pickles are not migrated automatically, earlier branded archives are not guaranteed to load, and experiments created under an old execution identity must be rerun. Migration and provenance details.

Local development

From a checkout, use Python 3.12–3.14 and uv:

uv sync --locked --extra test --group docs
uv run --locked python examples/advanced/native_run.py
uv run --locked python -m pytest tests/test_inputs.py -q
uv run --locked --group docs mkdocs serve

The last command keeps a live documentation preview at http://127.0.0.1:8000; use Ctrl+C to stop it. Core source is under src/openbacktesting/, tests under tests/, and the manual under docs/core/.

Studio has its own Python host, frontend, and tests under studio/. To develop it, build the interface with Node.js 22.12+, install core and Studio in editable mode, then run the local Python host. Follow the Studio development steps for exact commands and the current frontend rebuild workflow. Core-only and documentation work do not require Node.js.

See local development and validation for environment setup, focused and full checks, generated documentation, and clean package-installation checks.

Share code and contribute

Read CONTRIBUTING.md and the contribution guide for the full workflow:

1. Search issues and PRs; discuss substantial features or compatibility changes first.
2. Fork the repository, create a focused branch from upstream main, and make the change with appropriate tests, examples, and documentation.
3. Run the relevant checks, inspect the staged diff, and open a PR against lucidcog/openbacktesting:main describing the problem, resulting behavior, and actual validation.

For bug reports or shared strategies, include a minimal reproducer, versions, settings, and small synthetic or redistributable data. Keep credentials, private datasets, generated assets, and local run history out of commits. Studio result archives can be shared separately; include source and data only when intended and permitted. Code and general documentation use English; OpenSpec planning records use Simplified Chinese. Preserve the project license and third-party notices.

Translations

This English README is the source of truth. Translations cover Simplified Chinese, Spanish, Brazilian Portuguese, French, German, Italian, and Hindi. Use the language links above, and follow the translation guide when updating them. Keep commands, API identifiers, capability boundaries, and sponsor attribution consistent across languages.

License and provenance

The project license declaration is Apache-2.0. Third-party materials retain their original licensing terms, including the indicator reference data.