Workflow:Nautechsystems Nautilus trader Backtest with BacktestEngine
| Knowledge Sources | |
|---|---|
| Domains | Algorithmic_Trading, Backtesting, Quantitative_Finance |
| Last Updated | 2026-02-10 09:00 GMT |
Overview
End-to-end process for running event-driven historical backtests of trading strategies using the NautilusTrader BacktestEngine on simulated exchange venues.
Description
This workflow covers the complete procedure for backtesting a trading strategy against historical market data using NautilusTrader's BacktestEngine. The engine creates a simulated exchange environment that replicates real venue behavior, including order matching, fill models with configurable slippage, latency simulation, and commission calculations. The process spans from engine configuration and venue setup through data loading, strategy attachment, execution, and post-run performance analysis. Strategies written for backtesting are fully portable to live trading without code changes, ensuring parity between simulation and production.
Usage
Execute this workflow when you have historical market data (trade ticks, quote ticks, bars, or order book deltas) and want to evaluate a trading strategy's performance before deploying it to live markets. The BacktestEngine is the primary entry point for single-run backtests with programmatic setup. Use this workflow when you need direct control over venue configuration, data loading, and engine lifecycle, or when backtesting a single strategy on a single dataset.
Execution Steps
Step 1: Configure the BacktestEngine
Create a BacktestEngineConfig specifying the trader ID, logging configuration, and optional parameters such as strategy start/stop times. Instantiate the BacktestEngine with this configuration. The engine initializes the internal event loop, message bus, cache, data engine, execution engine, risk engine, and portfolio manager.
Key considerations:
- Set a unique TraderId for identification in logs and reports
- Configure logging level (DEBUG for development, INFO for production runs)
- Optionally set bypass_logging to True for maximum throughput benchmarks
Step 2: Add Trading Venues
Register one or more simulated exchange venues with the engine. Each venue requires specification of the order management system type (NETTING or HEDGING), account type (CASH or MARGIN), base currency, starting balances, and optionally a fill model, latency model, commission model, and simulation modules (such as FX rollover interest).
Key considerations:
- NETTING collapses positions into a single net position per instrument; HEDGING allows multiple independent positions
- Starting balances define the initial account equity and determine available margin
- FillModel controls probabilistic slippage and partial fill behavior
- Multiple venues can be added for cross-exchange strategy testing
Step 3: Add Instruments
Register the financial instruments that will be traded during the backtest. Instruments define the contract specification including tick size, lot size, price precision, quantity precision, and margin requirements. Instruments can be loaded from test providers, created programmatically, or loaded from a data catalog.
Key considerations:
- Instrument definitions must match the data being loaded (same instrument IDs)
- NautilusTrader supports equities, FX pairs, crypto perpetuals, futures, options, and betting instruments
- The instrument's venue must match a venue already added to the engine
Step 4: Load Historical Data
Transform raw historical data into NautilusTrader data objects and add them to the engine. Data wranglers convert CSV or DataFrame sources into typed objects (TradeTick, QuoteTick, Bar, OrderBookDelta). The engine accepts multiple data types simultaneously and merges them chronologically during execution.
Key considerations:
- Use TradeTickDataWrangler for trade execution data
- Use QuoteTickDataWrangler for bid/ask quote data
- Use BarDataWrangler for OHLCV bar data
- Data timestamps must be timezone-aware (UTC)
- Multiple data types can be loaded and will be interleaved by timestamp
Step 5: Configure and Add Strategy
Create a strategy configuration with instrument-specific parameters (instrument ID, bar type, trade size, indicator periods, etc.) and instantiate the strategy class. Add the strategy to the engine. Multiple strategies can run simultaneously, each receiving the same data stream and independently submitting orders.
Key considerations:
- Strategy classes inherit from the Strategy base class
- Configuration is passed via a StrategyConfig subclass for serialization support
- Strategies subscribe to data in their on_start() method
- The same strategy code works identically in backtest and live environments
Step 6: Run the Backtest
Execute the backtest by calling engine.run(). The engine iterates through all loaded data chronologically, dispatching events to subscribed strategies. Each data event triggers the simulated exchange's order matching engine, which processes pending orders, generates fills, and emits position/account events. Optionally specify start and end timestamps to run a subset of the data.
Key considerations:
- The engine processes data in strict chronological order across all data types
- Order matching occurs after each data event, ensuring realistic fill timing
- The run is deterministic: identical inputs always produce identical outputs
- Use engine.run(start=..., end=...) to restrict the simulation window
Step 7: Analyze Results and Generate Reports
After the run completes, extract performance reports from the engine's trader component. Generate account reports (equity curve, balances), order fill reports, and position reports. Optionally create interactive tearsheet visualizations with equity curves, drawdown analysis, and portfolio statistics (Sharpe ratio, Sortino ratio, profit factor, win rate, etc.).
Key considerations:
- Reports are generated as pandas DataFrames for easy analysis
- The PortfolioAnalyzer computes 15+ statistics including Sharpe, Sortino, and Expectancy
- Tearsheets can be exported as interactive HTML files
- Use engine.reset() to run another scenario without full reinitialization
- Call engine.dispose() to release all resources when finished