backtesting.py y backtrader: dos motores didácticos y su estado.

Dos motores con los que aprendió mucha gente

Antes de NautilusTrader o de vectorbt, quien quería hacer un backtest en Python con algo más que pandas acababa casi siempre en una de estas dos librerías. backtrader es un motor por eventos completo, con varios activos, muchos tipos de orden, comisiones de futuros y conexión con brokers. backtesting.py es más pequeño y más directo: una estrategia, un instrumento, un DataFrame, un informe y un gráfico interactivo. Las dos se llaman a menudo «didácticas» porque se leen bien y enseñan la estructura de un motor; la lección 2.4.2 construyó esa misma estructura desde cero, así que aquí se pueden leer con ojo crítico.

En este curso no se ejecutan (decisión del titular): su código aparece en bloques sin ejecutar, tal como lo documentan las propias librerías, y la parte ejecutable reproduce con código propio la decisión de diseño que más cambia sus resultados. Su estado, leído en PyPI y GitHub el 21 de octubre de 202611Nota 1 · Metadatos de PyPI de backtesting, backtrader e IbPy2 (versiones, fechas, licencia y clasificadores) y repositorios kernc/backtesting.py y mementum/backtrader en GitHub (licencia, último commit, estado de archivo), consultados el 21 de octubre de 2026.:

La figura enseña la historia de publicaciones. backtesting.py tuvo un parón entre diciembre de 2021 y enero de 2025 y volvió a publicar con regularidad; backtrader publicó en PyPI cinco versiones y ninguna desde abril de 2023. Que una librería sin versiones nuevas siga funcionando con un Python moderno es posible, pero no está garantizado: no recibe correcciones ni adaptaciones a los cambios de pandas, NumPy o Matplotlib, y sus dependencias de conexión en real (IbPy para Interactive Brokers, según su README) tampoco se mueven: el paquete IbPy2 de PyPI publicó su última versión, la 0.8.0, en octubre de 2016.

Las licencias importan si vas a distribuir algo. Las dos son copyleft. La GPL-3.0 de backtrader exige que, si se distribuye un programa que incluye o deriva de ella, se distribuya con su código fuente y con la misma licencia. La AGPL-3.0 de backtesting.py añade el uso en red: quien ofrece a usuarios remotos una versión modificada como servicio tiene que darles acceso a ese código. Para un trader que importa la librería en sus propios scripts y opera con su dinero no hay nada que publicar. Para quien quiera montar una plataforma o un producto, conviene leer el texto de la licencia con un abogado antes de escribir la primera línea; es la misma advertencia que la Commons Clause de vectorbt (lección 2.4.3), con otras condiciones.

backtesting.py: una estrategia en una clase

La estrategia hereda de Strategy y define dos métodos. En init() se declaran los indicadores con self.I(), que los calcula de una vez sobre toda la serie y luego los revela barra a barra: dentro de next(), self.ma1 solo contiene los valores hasta la barra actual. En next() se decide. El ejemplo de su README, con los datos de ejemplo que trae la librería:

from backtesting import Backtest, Strategy
from backtesting.lib import crossover
from backtesting.test import SMA, GOOG


class SmaCross(Strategy):
    def init(self):
        price = self.data.Close
        self.ma1 = self.I(SMA, price, 10)
        self.ma2 = self.I(SMA, price, 20)

    def next(self):
        if crossover(self.ma1, self.ma2):
            self.buy()
        elif crossover(self.ma2, self.ma1):
            self.sell()


bt = Backtest(GOOG, SmaCross, commission=.002,
              exclusive_orders=True)
stats = bt.run()
bt.plot()

Backtest recibe un DataFrame con columnas Open, High, Low, Close (y Volume opcional) y la clase de la estrategia. Sus parámetros, según la documentación de la API: cash (10.000 por defecto), spread, commission (en fracción del valor de la orden, aplicada a la entrada y a la salida desde la versión 0.4.0; admite también un mínimo fijo o una función), margin (1 = sin apalancamiento), trade_on_close, hedging, exclusive_orders (cada orden nueva cierra la posición anterior) y finalize_trades. Lo importante está en una frase de la documentación de buy(): salvo con trade_on_close=True, las órdenes de mercado se ejecutan a la apertura de la barra siguiente; las limitadas y las stop, cuando se cumple su condición.

La optimización viene incluida:

stats, heatmap = bt.optimize(
    n1=range(5, 60, 5), n2=range(20, 300, 10),
    constraint=lambda p: p.n1 < p.n2,
    maximize="Sharpe Ratio", method="grid",
    return_heatmap=True)

maximize es una clave de la serie de resultados de run() (por defecto, el SQN de Van Tharp) o una función; method puede ser "grid" (todas las combinaciones, o una muestra si se limita con max_tries) o "sambo" (optimización basada en modelos). Para que n1 y n2 sean parámetros, la estrategia los declara como atributos de clase y los usa en init(). La advertencia de la lección 2.4.3 vale igual: optimize devuelve el máximo de un barrido, y el máximo de un barrido es en buena parte ruido.

Sus límites, de la propia documentación: un Backtest es un instrumento. MultiBacktest ejecuta la misma estrategia sobre varios por separado, para comparar, no una cartera con caja compartida. Para fracciones de unidad (cripto) existe FractionalBacktest. backtesting.lib trae piezas útiles, como crossover, resample_apply para varios marcos temporales y TrailingStrategy, un trailing stop expresado en múltiplos del ATR (y, con set_trailing_pct, un porcentaje que la documentación advierte que es inexacto porque se convierte a ATR).

backtrader: Cerebro, líneas y next()

backtrader es un motor por eventos con más piezas. Cerebro es el coordinador: recibe los datos, las estrategias, el broker y los complementos, y ejecuta el bucle.

flowchart TB
  C[Cerebro] --> D[Data feeds]
  C --> S[Strategy]
  C --> B[Broker]
  C --> A[Analyzers]
  C --> O[Observers]
  D --> S
  Z[Sizer] --> S
  S --> B
  B --> S

• Data feeds: CSV, pandas (bt.feeds.PandasData), proveedores en línea o en real; varios a la vez, con remuestreo y repetición de barras.
• Strategy: __init__ declara indicadores (bt.ind.SMA, bt.ind.CrossOver…) y next() decide en cada barra; notify_order y notify_trade reciben los cambios de estado de órdenes y operaciones.
• Broker: el simulado (BackBroker) con comisiones (setcommission), deslizamiento (set_slippage_perc) y los modos set_coc (ejecutar al cierre) y set_coo (a la apertura); o uno real.
• Sizer: decide el tamaño cuando la estrategia no lo da. Analyzers (SharpeRatio, DrawDown, TradeAnalyzer…) y observers calculan métricas y series para el gráfico.

Las series son líneas: self.data.close[0] es el cierre de la barra actual y self.data.close[-1] el de la anterior, sin que la estrategia sepa en qué barra está. La misma estrategia que en backtesting.py, al estilo de la documentación de backtrader:

import backtrader as bt
import pandas as pd


class SmaCross(bt.Strategy):
    params = (("rapida", 10), ("lenta", 30))

    def __init__(self):
        sma1 = bt.ind.SMA(period=self.p.rapida)
        sma2 = bt.ind.SMA(period=self.p.lenta)
        self.cruce = bt.ind.CrossOver(sma1, sma2)

    def next(self):
        if not self.position and self.cruce[0] > 0:
            self.buy()
        elif self.position and self.cruce[0] < 0:
            self.close()

    def notify_order(self, order):
        if order.status == order.Completed:
            print(self.data.datetime.date(0), order.executed.price)


df = pd.read_csv("kapa_diario.csv", index_col=0, parse_dates=True)
cerebro = bt.Cerebro()
cerebro.adddata(bt.feeds.PandasData(dataname=df))
cerebro.addstrategy(SmaCross, rapida=10, lenta=30)
cerebro.broker.setcash(10_000)
cerebro.broker.setcommission(commission=0.001)     # 0,1 %
cerebro.addanalyzer(bt.analyzers.SharpeRatio, _name="sharpe")
resultado = cerebro.run()
print(cerebro.broker.getvalue())

Para un futuro, la comisión se da por contrato junto con el margen y el multiplicador; el ejemplo de su documentación es el del Euro Stoxx 50 en Interactive Brokers:

cerebro.broker.setcommission(commission=2.0, margin=2000.0, mult=10.0)

# y un trailing stop del 4 % como orden del broker simulado
self.sell(exectype=bt.Order.StopTrail, trailpercent=0.04)

Con margin, backtrader trata el instrumento como un futuro: la comisión es fija por contrato y el efectivo se ajusta cada día con las pérdidas y ganancias, la contabilidad que la cartera de la lección 2.4.2 simplificaba. StopTrail recalcula el stop con el último cierre y, cuando se toca, lo ejecuta como orden de mercado, según su documentación.

Un adaptador con la semántica de next()

Ninguna de las dos librerías se ejecuta aquí, pero su regla central sí se puede reproducir y medir: una estrategia escrita como en backtrader, con líneas indexadas desde la barra actual y órdenes que se ejecutan a la apertura de la barra siguiente, sobre un pequeño motor propio con el orden de eventos de la lección 2.4.2. Los datos son las barras diarias de KAPA, el ETF sintético de 2022 a 2025 de las lecciones anteriores, construidas desde sus barras de 5 minutos.

flowchart LR
  N[next en barra t] --> O[Orden de mercado]
  O --> A[Apertura de t+1]
  O --> C[Cierre de t: coc]

import numpy as np
import pandas as pd

b5 = pd.read_parquet("indice2_5min.parquet")
b5["sesion"] = (b5["ts"].dt.tz_convert("America/New_York")
                .dt.tz_localize(None).dt.normalize())
kapa = b5.groupby("sesion").agg(open=("apertura", "first"),
                                high=("maximo", "max"),
                                low=("minimo", "min"),
                                close=("cierre", "last"))
hueco = kapa["open"] / kapa["close"].shift(1) - 1
print(len(kapa), "sesiones; hueco nocturno medio absoluto:",
      f"{100 * hueco.abs().mean():.2f} %")

1003 sesiones; hueco nocturno medio absoluto: 0.38 %

Primero, las líneas. Una Linea guarda toda la serie pero solo deja leer hasta la barra actual: [0] es la actual, [-1] la anterior y [1], el futuro, es un error. Un indicador es otra línea, calculada de una vez pero revelada al mismo ritmo, que es exactamente lo que hace self.I() en backtesting.py.

class Reloj:
    def __init__(self):
        self.i = -1                       # índice de la barra actual

class Linea:
    """Serie revelada barra a barra: [0] actual, [-1] anterior."""

    def __init__(self, valores, reloj):
        self.v, self.reloj = np.asarray(valores, dtype=float), reloj

    def __getitem__(self, k):
        if k > 0:
            raise IndexError(f"[{k}] es el futuro")
        j = self.reloj.i + k
        return self.v[j] if j >= 0 else np.nan

def sma(linea, n):
    return Linea(pd.Series(linea.v).rolling(n).mean(), linea.reloj)

def cruce(a, b):
    """+1 si a cruza b al alza en la barra, -1 a la baja, 0 si no."""
    d = np.sign(a.v - b.v)
    previo = np.concatenate([[np.nan], d[:-1]])
    return Linea(np.where((d > 0) & (previo <= 0), 1,
                 np.where((d < 0) & (previo >= 0), -1, 0)), a.reloj)

reloj = Reloj()
prueba = Linea([10.0, 11.0, 12.0], reloj)
reloj.i = 1
print(prueba[0], prueba[-1], prueba[-2])
try:
    prueba[1]
except IndexError as e:
    print("IndexError:", e)

11.0 10.0 nan
IndexError: [1] es el futuro

Después, el adaptador: un motor mínimo que llama a next() en cada barra y ofrece a la estrategia lo que espera de backtrader (self.data, self.position, buy(), close(), notify_order()). El orden de las cosas en cada barra es el de la lección 2.4.2: primero se ejecutan las órdenes pendientes con la apertura de la barra, después decide la estrategia. Con coc=True (como set_coc(True) en backtrader o trade_on_close=True en backtesting.py) la orden se ejecuta al cierre de la barra en la que se envía. Para que la comparación sea exacta, cada compra invierte todo el capital en el momento de ejecutarse, sin comisiones.

class Datos:
    def __init__(self, df, reloj):
        for c in ("open", "high", "low", "close"):
            setattr(self, c, Linea(df[c], reloj))
        self.fechas = df.index

class Orden:
    def __init__(self, objetivo, fecha):
        self.objetivo, self.creada = objetivo, fecha
        self.status = "Submitted"
        self.precio, self.ejecutada = None, None

class EstrategiaNext:
    """Lo mínimo de la API de backtrader que usa una estrategia."""

    def __init__(self, motor, data, **params):
        self.motor, self.data = motor, data
        self.p = type("Params", (), params)

    @property
    def position(self):
        return self.motor.unidades

    def buy(self):
        return self.motor.enviar(1.0)     # todo el capital

    def close(self):
        return self.motor.enviar(0.0)

    def notify_order(self, orden):
        pass

class MiniCerebro:
    def __init__(self, df, coc=False, cash=1.0):
        self.df, self.coc = df, coc
        self.reloj = Reloj()
        self.efectivo, self.unidades = cash, 0.0
        self.pendientes, self.ordenes = [], []

    def enviar(self, objetivo):
        o = Orden(objetivo, self.df.index[self.reloj.i])
        if self.coc:
            self._ejecutar(o, self.df["close"].iloc[self.reloj.i])
        else:
            self.pendientes.append(o)
        return o

    def _ejecutar(self, o, precio):
        valor = self.efectivo + self.unidades * precio
        self.unidades = o.objetivo * valor / precio
        self.efectivo = valor - self.unidades * precio
        o.status, o.precio = "Completed", precio
        o.ejecutada = self.df.index[self.reloj.i]
        self.ordenes.append(o)
        self.estrategia.notify_order(o)

    def run(self, clase, **params):
        datos = Datos(self.df, self.reloj)
        self.estrategia = clase(self, datos, **params)
        capital = []
        for i in range(len(self.df)):
            self.reloj.i = i
            for o in self.pendientes:     # órdenes de la barra anterior
                self._ejecutar(o, self.df["open"].iloc[i])
            self.pendientes = []
            self.estrategia.next()
            capital.append(self.efectivo + self.unidades
                           * self.df["close"].iloc[i])
        return pd.Series(capital, self.df.index)

La estrategia se escribe como en backtrader: indicadores en __init__, decisión en next() con índices relativos a la barra actual.

class SmaCross(EstrategiaNext):
    def __init__(self, motor, data, **params):
        super().__init__(motor, data, **params)
        rapida = sma(self.data.close, self.p.rapida)
        lenta = sma(self.data.close, self.p.lenta)
        self.cruce = cruce(rapida, lenta)

    def next(self):
        if not self.position and self.cruce[0] > 0:
            self.buy()
        elif self.position and self.cruce[0] < 0:
            self.close()

resultados = {}
for coc in (True, False):
    motor = MiniCerebro(kapa, coc=coc)
    eq = motor.run(SmaCross, rapida=10, lenta=30)
    nombre = "al cierre (coc)" if coc else "apertura siguiente"
    resultados[nombre] = (eq, motor.ordenes)
    print(f"{nombre:19s} capital {eq.iloc[-1]:.4f}, "
          f"órdenes {len(motor.ordenes)}")
o = resultados["apertura siguiente"][1][0]
print("primera orden:", o.creada.date(), "->", o.ejecutada.date(),
      "a", o.precio)

al cierre (coc)     capital 1.7151, órdenes 33
apertura siguiente  capital 1.6462, órdenes 33
primera orden: 2022-03-10 -> 2022-03-11 a 250.74

Las mismas señales y el mismo número de órdenes (33); distinto capital final: 1,7151 ejecutando al cierre de la señal y 1,6462 a la apertura siguiente. La primera orden se crea en next() del 10 de marzo de 2022 y se ejecuta a la apertura del 11, a 250,74. Que la diferencia no es un error del adaptador se demuestra igual que en la lección 2.4.2: reconciliando con un cálculo vectorizado que aplica cada convención. Al cierre es el shift(1) de siempre; a la apertura siguiente, la posición nueva empieza a la apertura y la noche anterior se pasa con la posición vieja.

c, o_ = kapa["close"], kapa["open"]
x = np.sign(c.rolling(10).mean() - c.rolling(30).mean())
cruce_s = pd.Series(np.where((x > 0) & (x.shift(1) <= 0), 1,
                    np.where((x < 0) & (x.shift(1) >= 0), -1, 0)),
                    kapa.index)
# estado tras next() de cada barra (largo o fuera), con memoria
estado = cruce_s.replace(0, np.nan).clip(lower=0).ffill().fillna(0)

r_cierre = estado.shift(1, fill_value=0) * c.pct_change().fillna(0)
s1 = estado.shift(1, fill_value=0)       # posición desde la apertura
s2 = estado.shift(2, fill_value=0)       # posición durante la noche
r_apertura = ((1 + s2 * (o_ / c.shift(1) - 1).fillna(0))
              * (1 + s1 * (c / o_ - 1)) - 1)
for nombre, rv in [("al cierre (coc)", r_cierre),
                   ("apertura siguiente", r_apertura)]:
    eq_v = (1 + rv).cumprod()
    dif = (resultados[nombre][0] / eq_v - 1).abs().max()
    print(f"{nombre:19s} vectorizado {eq_v.iloc[-1]:.4f}  "
          f"diferencia máxima {dif:.1e}")

al cierre (coc)     vectorizado 1.7151  diferencia máxima 2.3e-15
apertura siguiente  vectorizado 1.6462  diferencia máxima 2.8e-15

Los dos se reconcilian al redondeo de la coma flotante. La diferencia entre ellos sale entera del hueco nocturno: cada compra a la apertura paga (o cobra) lo que el precio se movió desde el cierre de la señal, y cada venta igual. En KAPA, un ETF sintético con un hueco nocturno medio del 0,38 %, son casi 7 puntos de capital en cuatro años; en un activo con huecos grandes (acciones con resultados, cripto con fines de semana, futuros con sesiones partidas) puede ser todo el resultado. Y fíjate en la trampa: un backtest vectorizado con shift(1) sobre cierres equivale al modo coc, el que backtrader llama hacer trampa. Ejecutar al cierre de la señal solo es honesto si la señal se puede calcular y la orden enviar antes del cierre (lección 1.1.4).

La correspondencia entre las tres arquitecturas, la del motor de la lección 2.4.2 y las dos librerías:

Ojo a una diferencia de índices: en backtesting.py, self.data.Close es un array con los datos hasta la barra actual, así que la última es [-1]; en backtrader, la actual es [0]. Traducir una estrategia de una librería a otra sin tenerlo en cuenta desplaza todo una barra.

Cuál elegir

La figura de la cabecera resume las capacidades de cada uno según su documentación. Lo que ninguna tabla dice es cómo se comporta cada motor en los detalles (el orden de los eventos dentro de una barra, qué precio toma un stop con hueco, cuándo se calcula el tamaño de una orden). Antes de fiarte de un resultado, reconcílialo con algo independiente, como se ha hecho en esta lección y en la 2.4.2.

Ejercicios

1. Añade al adaptador una comisión proporcional (por ejemplo, 0,1 % del valor negociado, como setcommission(commission=0.001) de backtrader) y mide cuánto cambia el capital final en los dos modos de ejecución.

class MiniCerebroComision(MiniCerebro):
    def __init__(self, df, coc=False, comision=0.001):
        super().__init__(df, coc)
        self.comision = comision

    def _ejecutar(self, o, precio):
        antes = self.unidades
        super()._ejecutar(o, precio)
        self.efectivo -= abs(self.unidades - antes) * precio \
            * self.comision

for coc in (True, False):
    m = MiniCerebroComision(kapa, coc=coc)
    eq = m.run(SmaCross, rapida=10, lenta=30)
    print(f"coc={coc!s:5s} capital {eq.iloc[-1]:.4f}")

coc=True  capital 1.6601
coc=False capital 1.5934

2. Escribe en el estilo del adaptador una estrategia que use self.data.close[-1]: comprar si el cierre de hoy supera el máximo de los cierres de las 20 sesiones anteriores y salir si cae por debajo del mínimo de las 10 anteriores (un canal de Donchian, lección 2.3.1). ¿Por qué no se puede escribir con [1]?

class Donchian(EstrategiaNext):
    def next(self):
        cl = self.data.close
        if np.isnan(cl[-20]):
            return                         # aún no hay 20 anteriores
        previos = [cl[-k] for k in range(1, 21)]
        if not self.position and cl[0] > max(previos):
            self.buy()
        elif self.position and cl[0] < min(previos[:10]):
            self.close()

m = MiniCerebro(kapa)
eq = m.run(Donchian)
print(f"capital {eq.iloc[-1]:.4f}, órdenes {len(m.ordenes)}")

capital 1.4990, órdenes 47

3. Un compañero ha hecho un backtest con backtesting.py y otro con un vectorizado propio de la misma estrategia diaria y no le coinciden. Enumera tres causas que comprobarías antes de buscar un error, con lo visto en esta lección.