backtrader: a Python backtesting library for trading

Why you need to backtest before risking real capital

A trading strategy that looks good on a spreadsheet can still lose money once slippage, commissions, and order-fill timing get involved. Paper profits don't survive contact with real fills. Backtesting against historical price data is how you catch a strategy that only works because it was tuned on the same data it's later tested on, or one that assumes fills happen at the exact close price when they don't. backtrader exists so a Python trader can plug a strategy into historical data, run it through realistic order types and commission schemes, check the results, then switch that same strategy code to a live Interactive Brokers or Oanda feed.

What is backtrader?

backtrader is a Python library for backtesting and live trading of algorithmic strategies. It centers on the Cerebro engine, which wires together data feeds, a strategy class, 122 built-in indicators, and a simulated broker so you can run a strategy against historical data before risking real money. Written entirely in Python, it drops into an existing project as a pip install rather than running as a separate application.

Key capabilities: data feeds, indicators, and order types

• ✓The Cerebro engine coordinates strategies, data feeds, and broker simulation in a single run
• ✓122 built-in indicators, plus TA-Lib indicator support when the python ta-lib package is installed
• ✓Features simulated broker trading with Market, Close, Limit, Stop, StopLimit, StopTrail, as well as StopTrailLimit and OCO order types, with bracket orders and slippage support
• ✓Data feeds from CSV files, online sources, pandas DataFrames, and blaze
• ✓Multiple data feeds, multiple strategies, and multiple timeframes in one run, with integrated resampling and replaying
• ✓Live trading feeds for Interactive Brokers, Visual Chart, and Oanda
• ✓Analyzers such as TimeReturn, Sharpe Ratio, and SQN, plus a pyfolio integration the README marks deprecated
• ✓Sizers for automated position staking, trading calendars, and schedulers

Installing backtrader and its dependencies

Install with `pip install backtrader`; the core library has no external dependencies. For charts, install the plotting extra instead: `pip install backtrader[plotting]`, which needs matplotlib 1.4.1 or newer. It supports Python >= 3.2, and also runs under pypy and pypy3 (without plotting, since matplotlib isn't supported there). Live trading against Interactive Brokers needs IbPy installed separately; the README says it isn't on PyPI, so you install it with `pip install git+https://github.com/blampe/IbPy.git`. You can also skip pip entirely and drop the backtrader directory from the source distribution straight into your project.

Writing your first backtest with backtrader

A minimal backtrader script has three moving parts: a `bt.Strategy` (or `bt.SignalStrategy`) subclass that defines your logic, a `bt.Cerebro` instance that runs everything, and one or more data feeds. The README's own example builds a simple moving-average crossover: define two `bt.ind.SMA` indicators inside the strategy, wire a `bt.ind.CrossOver` between them, and register it with `self.signal_add(bt.SIGNAL_LONG, crossover)`. Outside the strategy class, create `cerebro = bt.Cerebro()`, add the strategy with `cerebro.addstrategy(...)`, load historical data with `cerebro.adddata(...)`, then call `cerebro.run()` to execute the backtest and `cerebro.plot()` to chart it if matplotlib is installed. The same sample ships as `sigsmacross/sigsmacross2.py` in the project's examples.

Alternatives

Frequently asked questions about backtrader

Best use cases

• •Testing a moving-average crossover or other rules-based strategy against years of historical CSV or pandas data before funding it
• •Comparing order-execution assumptions (market vs. limit vs. stop) to see how fill logic changes a strategy's returns
• •Running the same strategy code in backtest mode and then against a live Interactive Brokers or Oanda feed without a rewrite
• •Writing a custom indicator when none of the 122 shipped ones fit

Who should try it — and who should skip

backtrader fits Python developers who already know how to code and want control over strategy logic, order types, and commission modeling rather than a drag-and-drop backtesting UI. It also suits anyone who wants to backtest and then live-trade through Interactive Brokers or Oanda using the same strategy class. Skip it if you want a no-code tool, if you need vectorized backtesting across huge parameter sweeps (the step-by-step Cerebro engine isn't built for that), or if you're not willing to work through metaclass-heavy internals when something breaks.

Related repositories