Backtrader

Common errors

• AttributeError: 'module' object has no attribute 'Cerebro'

  cause Attempting to access a backtrader component directly (e.g., `backtrader.Cerebro`) without importing backtrader with the standard alias.
  fix Always use `import backtrader as bt` and then refer to components as `bt.Cerebro`, `bt.Strategy`, etc.

• ModuleNotFoundError: No module named 'matplotlib'

  cause The `cerebro.plot()` method was called, but the `matplotlib` library is not installed.
  fix Install `matplotlib`: `pip install matplotlib` or `pip install backtrader[plotting]`.

• ValueError: No data points left to run a strategy (fromdate/todate problem?)
  TypeError: object of type 'NoneType' has no len()

  cause This usually indicates that the data feed could not be loaded correctly, or the specified `fromdate`/`todate` range for the data is empty/invalid. Common reasons include incorrect file path, wrong `datetimeformat`, or an empty data file.
  fix Verify the `dataname` path, `datetimeformat` string, and ensure the `fromdate`/`todate` range correctly overlaps with available data. Check the content of your data file for correctness and headers.

• FileNotFoundError: [Errno 2] No such file or directory: 'your_data.csv'

  cause The path provided to a data feed (e.g., `bt.feeds.CSVData(dataname='your_data.csv')`) is incorrect or the file does not exist at that location.
  fix Double-check the file path. Ensure it's either an absolute path or a path relative to where your script is being run. Use `os.path.abspath()` for debugging if unsure.

Warnings

• breaking The upcoming backtrader 2.0 release (currently in pre-release/beta) introduces significant breaking changes, including module restructuring and API renames (e.g., `bt.Cerebro` moves to `bt.core.Cerebro`).
  Fix: Refer to the official 2.0 documentation for updated import paths and API usage when migrating. For current projects, stick to 1.x.
• gotcha backtrader internally processes all datetime objects as UTC. If your input data feed contains timezone-aware datetimes or is in a local timezone, ensure you convert it to UTC or set the correct timezone conversion parameters in your data feed (`dtformat`, `tz`, `tzislocal`).
  Fix: Use `datetimeformat='%Y-%m-%d %H:%M:%S'` and `tz='UTC'` or ensure your input data is already UTC. For pandas feeds, use `pd.to_datetime(..., utc=True)` before creating the feed.
• gotcha Calling `cerebro.plot()` will raise a `ModuleNotFoundError` or similar error if `matplotlib` is not installed in your environment.
  Fix: Install matplotlib: `pip install matplotlib` or `pip install backtrader[plotting]`.
• gotcha Strategy and indicator parameters must be defined within a `params` tuple in the class, not as instance attributes in `__init__`.
  Fix: Define `params = (('my_param', default_value),)` at the class level. Access them within the strategy via `self.p.my_param`.

Install

• pip install backtrader Install stable version
• pip install backtrader[plotting,pandas] Install with common optional dependencies

Imports

• bt

  import backtrader as bt

• Cerebro
  wrong:

  from backtrader import Cerebro

  correct:

  import backtrader as bt
  cerebro = bt.Cerebro()

  While direct imports sometimes work, the standard and recommended practice is 'import backtrader as bt' and then access components via 'bt.<component>'.
• Strategy
  wrong:

  from backtrader.strategy import Strategy

  correct:

  import backtrader as bt
  class MyStrategy(bt.Strategy):

  See note for Cerebro; prefer accessing via the 'bt' alias.
• CSVData
  wrong:

  from backtrader.feeds import CSVData

  correct:

  import backtrader as bt
  data = bt.feeds.CSVData(...)

  See note for Cerebro; prefer accessing via the 'bt' alias.

Quickstart

This quickstart demonstrates how to set up a basic backtesting strategy with backtrader. It involves defining a strategy with two moving averages, adding a CSV data feed (a dummy one created for demonstration), setting initial cash and commission, running the backtest, and printing the portfolio value. The `cerebro.plot()` line is commented out but shows how to visualize results if `matplotlib` is installed.

import backtrader as bt
import datetime
import os

# Dummy CSV data for demonstration. In a real scenario, this would be a file.
dummy_csv_content = (
    "Date,Open,High,Low,Close,Volume,OpenInterest\n"
    "2020-01-01,100,102,99,101,1000,0\n"
    "2020-01-02,101,103,100,102,1200,0\n"
    "2020-01-03,102,104,101,103,1100,0\n"
    "2020-01-06,103,105,102,104,1300,0\n"
)

# Create a dummy CSV file
dummy_csv_path = 'dummy_data.csv'
with open(dummy_csv_path, 'w') as f:
    f.write(dummy_csv_content)

class SmaCross(bt.Strategy):
    params = (('fast_period', 10), ('slow_period', 30),)

    def __init__(self):
        self.sma_fast = bt.indicators.SMA(self.data.close, period=self.p.fast_period)
        self.sma_slow = bt.indicators.SMA(self.data.close, period=self.p.slow_period)
        self.crossover = bt.indicators.CrossOver(self.sma_fast, self.sma_slow)

    def next(self):
        if not self.position:  # Not in the market
            if self.crossover > 0:  # fast crosses slow upwards
                self.buy()
        elif self.crossover < 0:  # fast crosses slow downwards
            self.close()

cerebro = bt.Cerebro()
cerebro.addstrategy(SmaCross)

# Add data feed
data = bt.feeds.CSVData(
    dataname=dummy_csv_path,
    datetimeformat='%Y-%m-%d',
    fromdate=datetime.datetime(2020, 1, 1),
    todate=datetime.datetime(2020, 1, 31)
)
cerebro.adddata(data)

cerebro.broker.setcash(100000.0)
cerebro.broker.setcommission(commission=0.001)

print(f'Starting Portfolio Value: {cerebro.broker.getvalue():.2f}')
cerebro.run()
print(f'Final Portfolio Value: {cerebro.broker.getvalue():.2f}')

# Clean up dummy file
os.remove(dummy_csv_path)

# To plot results (requires matplotlib):
# cerebro.plot()