Module 00: Environment Setup & First RunGet from zero to your first backtest in under 30 minutes.

This module walks you through the required toolchain and your first backtest with a minimal strategy. At this stage, the goal is to confirm that your environment works end to end.

1. Prerequisites and Dependencies

flowchart LR
                        subgraph os["💻 Operating System"]
                        direction TB
                        linux["Linux (Recommended)"]
                        mac["macOS"]
                        wsl["Windows WSL2"]
                        end

                        subgraph tools["🔧 Toolchain"]
                        direction TB
                        python["Python 3.11+"]
                        uv["uv Package Manager"]
                        end

                        subgraph nautilus["🐚 NautilusTrader"]
                        direction TB
                        pip_install["pip install"]
                        source["Compile from Source"]
                        end

                        os ==> tools ==> nautilus

2. Step-by-Step Installation

Step 1: Verify Python Version

# Check Python version (requires >= 3.11)
python3 --version
# Expected Output: Python 3.11.x or 3.12.x

# 💡 Why >= 3.11?
# NautilusTrader leverages several Python 3.11 features:
#   - tomllib (for TOML configuration parsing)
#   - Significantly faster startup times (CPython optimizations)
#   - Enriched error messaging

# ❌ What if I use Python 3.9?
#   pip install nautilus_trader
#   → ERROR: Requires-Python >=3.11

Step 2: Install NautilusTrader

# Method 1: Using pip (Simplest)
pip install -U nautilus_trader

# Method 2: Using uv (Much faster, Highly Recommended)
pip install uv
uv pip install nautilus_trader

# 💡 Why recommend uv?
# uv is an ultra-fast Python package manager written in Rust.
# ❌ pip install nautilus_trader → Can take 2-5 minutes
# ✅ uv pip install nautilus_trader → Usually done in 10-30 seconds

Step 3: Installation Verification

# Verify inside the Python interpreter
import nautilus_trader
print(nautilus_trader.__version__)
# Example Output: 1.208.0

# Verify that core C-extension components load correctly
from nautilus_trader.backtest.node import BacktestNode
from nautilus_trader.model.data import QuoteTick, Bar
from nautilus_trader.trading.strategy import Strategy
print("✅ Core components loaded successfully!")

# Ubuntu/Debian
sudo apt install python3.11-dev

# If you see Rust-related compiler errors (when compiling from source)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. Your First Backtest: Hello NautilusTrader

Below is a minimal backtest example. It places no trades and is only meant to verify that your runtime environment is working correctly.

"""
Your first NautilusTrader Backtest — Hello World
Save this code to a file named hello_nautilus.py, and run it using `python hello_nautilus.py`
"""
from nautilus_trader.backtest.engine import BacktestEngine
from nautilus_trader.backtest.engine import BacktestEngineConfig
from nautilus_trader.model.currencies import USD
from nautilus_trader.model.data import QuoteTick
from nautilus_trader.model.enums import AccountType, OmsType
from nautilus_trader.model.identifiers import Venue
from nautilus_trader.model.objects import Money
from nautilus_trader.trading.strategy import Strategy
from nautilus_trader.config import StrategyConfig

# ── 1. Define a Minimalist Strategy ────────────────────────
class DoNothingConfig(StrategyConfig, frozen=True):
    """Minimalist StrategyConfig: no parameters."""
    pass

class DoNothingStrategy(Strategy):
    """
    This strategy executes no operations.
    Its sole purpose is to validate the execution environment.
    """
    def __init__(self, config: DoNothingConfig):
        super().__init__(config)

    def on_start(self):
        self.log.info("🚀 Strategy initialized. Environment validated.")

    def on_stop(self):
        self.log.info("🛑 Strategy terminated. Initial backtest execution successful.")

# ── 2. Configure the Backtest Engine ───────────────────────
config = BacktestEngineConfig(
    logging_level="INFO",        # Output logs to standard output
    logging_level_file=None,     # Disable file logging
)

engine = BacktestEngine(config=config)

# ── 3. Register a Venue (Exchange) ─────────────────────────
SIM = Venue("SIM")  # "SIM" represents a simulated venue
engine.add_venue(
    venue=SIM,
    oms_type=OmsType.NETTING,         # Netting OMS
    account_type=AccountType.MARGIN,  # Margin account type
    base_currency=USD,                # Account base currency
    starting_balances=[Money(100_000, USD)],  # Initial capital: $100,000
)

# ── 4. Register the Strategy ───────────────────────────────
strategy = DoNothingStrategy(config=DoNothingConfig())
engine.add_strategy(strategy)

# ── 5. Execute Backtest ────────────────────────────────────
engine.run()

# ── 6. Output Results ──────────────────────────────────────
print("\n" + "="*60)
print("📊 Backtest Results")
print("="*60)
print(f"Account Balances: {engine.portfolio.balances()}")
print(f"Total Orders: {len(engine.cache.orders())}")
print(f"Total Positions: {len(engine.cache.positions())}")
print("=" * 60)
print("✅ NautilusTrader environment is fully operational.")

# Dispose engine resources
engine.dispose()

INFO  DoNothingStrategy: 🚀 Strategy initialized. Environment validated.
INFO  DoNothingStrategy: 🛑 Strategy terminated. Initial backtest execution successful.

============================================================
📊 Backtest Results
============================================================
Account Balances: {USD: Money(100000.00, USD)}
Total Orders: 0
Total Positions: 0
============================================================
✅ NautilusTrader environment is fully operational.

4. Code Walkthrough

Even though the script is minimal, it demonstrates the core execution pattern of NautilusTrader:

flowchart LR
                        subgraph setup["⚙️ Configuration Phase"]
                        direction TB
                        config_engine["1. Configure Engine"]
                        add_venue["2. Register Venue"]
                        add_strategy["3. Register Strategy"]
                        config_engine --> add_venue --> add_strategy
                        end

                        subgraph run["▶️ Execution Phase"]
                        direction TB
                        init["Initialize Core Components"]
                        start["Invoke Strategy on_start()"]
                        process["Process Data Events"]
                        stop["Invoke Strategy on_stop()"]
                        init --> start --> process --> stop
                        end

                        subgraph result["📊 Analysis Phase"]
                        direction TB
                        balance["Query Account Balances"]
                        orders["Query Orders"]
                        tearsheet["Generate Tearsheet"]
                        end

                        setup ==> run ==> result

5. Python Survival Guide

If you are new to Python, below are the most frequent syntax patterns used in NautilusTrader. You do not need to master Python before starting; understanding these 7 core concepts is sufficient:

class MyStrategy(Strategy):
    # The strategy inherits from the Strategy base class
    # This automatically grants all base capabilities

def __init__(self, config):
    super().__init__(config)  # Let parent class process state first
    self.my_var = 0           # Then define custom variables safely

def on_start(self):
    self.log.info("...")      # Accesses the instance's unique logger
    self.count = 1            # Sets up the instance's unique counter

def on_bar(self, bar: Bar):
    # IDEs automatically resolve 'bar' attributes: open, high, low, close
    print(bar.close)

class MyConfig(StrategyConfig, frozen=True):
    symbol: str = "BTC-USDT"
    # c = MyConfig(...)
    # c.symbol = "ETH"  # ❌ Error! Configuration instances are immutable.

price = 100
self.log.info(f"The current price is {price}")  # Outputs: The current price is 100

from decimal import Decimal
qty = Decimal("0.1")  # ✅ Perfect precision
# qty = Decimal(0.1)  # ❌ Dangerous! Floating-point inaccuracies

6. Project Directory Map

Knowing the source tree makes debugging and tracing subsystem behavior much faster.

nautilus_trader/
├── model/           # 💎 Domain Model (Instruments, Orders, Positions)
|   |-- orders/      #     Order types and order-state logic
│   ├── instruments/ #     Instrument definitions (Equities, Futures, Options...)
│   ├── data.pyx     #     Market data structs (QuoteTick, Bar...)
│   └── position.pyx #     Position accounting
│
├── trading/         # 🎯 Strategy routing and execution
│   ├── strategy.pyx #     Strategy Base Class (inherited by custom strategies)
│   ├── trader.py    #     Main Trader Manager instance
│   └── controller.py#     Trading Controllers
│
├── data/            # 📊 Data Engine
│   ├── engine.pyx   #     Central hub
│   └── aggregation.pyx #  Bar aggregation
│
├── execution/       # ⚙️ Execution Engine
├── risk/            # 🛡️ Risk Engine (Throttlers/Rules)
├── cache/           # 💾 State Cache System
├── common/          # 🔧 Shared Modules (Actor, MessageBus, Logger)
│
├── backtest/        # 🔬 Backtest Engine
│   ├── engine.pyx   #     Backtest Kernel Hub
│   └── models/      #     FillModel, FeeModel, LatencyModel
│
├── live/            # 🚀 Live Execution Engine
│   ├── node.py      #     TradingNode
│   ├── reconciliation.py # Order reconciliation
│   └── retry.py     #     Automated retry routines
│
├── adapters/        # 🔌 Exchange adapters (16+ integrations)
├── indicators/      # 📈 Built-in Cythonized technical indicators
├── accounting/      # 💰 Accounting & Margin calculations
├── analysis/        # 📋 Performance analysis & Tearsheets
├── persistence/     # 💿 Persistence frameworks (Parquet DataCatalog)
├── serialization/   # 📦 Protocol serialization (Arrow/MsgPack)
├── system/          # ⚡ System Core (Kernel)
└── config/          # ⚙️ Configuration data classes

7. Interactive Exercises

checks = {
    "nautilus_trader": True,
    "BacktestEngine": True,
    "Strategy": True,
    "QuoteTick": True,
}
try:
    import nautilus_trader
    from nautilus_trader.backtest.engine import BacktestEngine
    from nautilus_trader.trading.strategy import Strategy
    from nautilus_trader.model.data import QuoteTick
except ImportError as e:
    print(f"❌ Missing dependency: {e}")
else:
    for name in checks:
        print(f"  ✅ {name}")
    print(f"\nVersion: {nautilus_trader.__version__}")

from nautilus_trader.backtest.engine import BacktestEngine
from nautilus_trader.model.currencies import USD

engine = BacktestEngine()  # Error 1: missing config
engine.add_venue(
    venue="SIM",             # Error 2: wrong venue type
    oms_type="NETTING",      # Error 3: wrong enum type
    account_type=AccountType.MARGIN,
    base_currency=USD,
    starting_balances=[100000],
)

8. Module Recap