Nautilus Developer Environment Setup

The Nautilus developer_guide/environment_setup/ page is the contributor machine setup - a uv-pinned, Rust-required, Cap’n-Proto-compiled, PyO3-env-var dance for anyone hacking on the Nautilus core itself. Cortana is not in that audience. For Cortana MK3 the install path is the end-user prebuilt wheel documented in nautilus-getting-started.md: one uv pip install "nautilus_trader[ib]" against the spike’s fresh worktree, no Rust toolchain, no Cap’n Proto, no make install-tools, no PYO3_PYTHON env vars. The developer guide page exists to be explicitly NOT followed on Saturday 2026-05-09. The only piece of this page Cortana borrows is the uv preference itself (uv over plain pip for venv + dep management) and the macOS ARM64 supported-platform confirmation (Sequoia / Apple Silicon is officially supported per nautilus-getting-started.md). Everything else - pinned cargo-binstall, prek pre-commit, cargo-nextest, cranelift backend, Cap’n Proto from source, Postgres/Redis Docker compose, the LD_LIBRARY_PATH / PYTHONHOME exports - is contributor scaffolding the spike must skip. Confusing the two paths is the most likely Saturday-morning rabbit hole.

Why this page exists (vs. siblings)

nautilus-getting-started.md covers the one-line pip install that 99% of users (including Cortana MK3) take. nautilus-rust.md confirms the Rust toolchain is not required at runtime because wheels are prebuilt. This page covers the third path - building Nautilus itself from source as a contributor - and exists only so we can rule it out for the spike.

The spike plan (plans/2026-05-09-nautilus-spike.md Step 1) calls for:

mkdir -p ~/conductor/workspaces/cortanaroi-mk2/nautilus-spike
cd ~/conductor/workspaces/cortanaroi-mk2/nautilus-spike
uv venv && source .venv/bin/activate
uv pip install "nautilus_trader[ib]"
python -c "import nautilus_trader; print(nautilus_trader.__version__)"

That’s the end-user path - wheels, no compilation, target <10 min. The developer-guide page is for someone cloning github.com/nautechsystems/nautilus_trader and running uv sync --all-groups --all-extras + make build-debug. Do not confuse the two. If on Saturday the install starts compiling Rust crates or wants cargo-binstall, you’ve drifted into the wrong path - abort and re-read.

Two install paths (the cardinal distinction)

Audience	Source	Command	Rust?	Cap’n Proto?	Compile time
End user (Cortana)	PyPI wheel	`uv pip install "nautilus_trader[ib]"`	No	No	<10 min
Contributor (Nautilus core)	git clone + `uv sync`	`make install-tools && make build-debug`	Yes (1.95.0+)	Yes	30-90 min

The first row is nautilus-getting-started.md. The second row is this page. Cortana lives entirely in the first row through M5.

End-user prerequisites (the only ones that matter for Cortana)

Per nautilus-getting-started.md:

Python 3.12-3.14 (64-bit). Cortana MK2 already on 3.12+; verify before spike with python --version.
macOS 15.0+ ARM64 is officially supported. Cody is on macOS Sequoia (Apple Silicon) - confirmed in scope.
uv (curl -LsSf https://astral.sh/uv/install.sh | sh). Cody already has uv from MK2 work. Confirm with uv --version.
A virtual environment (strongly recommended; uv venv creates .venv/).

That’s the full prerequisite list for Cortana’s spike Step 1. Nothing else from this page applies.

What you do NOT need (counter-list, for confidence)

Rust toolchain - not required. nautilus-rust.md confirms: “End users do NOT need Rust - wheels are prebuilt.” If uv pip install triggers a Rust compile, the wheel for your Python+platform is missing - pick a supported Python version.
Cap’n Proto - not required at runtime. Required only for contributors recompiling serialization schemas. Wheels ship the compiled artifacts.
cargo-binstall, prek, osv-scanner, cargo-nextest - contributor toolchain. Skip.
make install-tools / make build-debug - these only exist in the cloned repo, not in the pip-installed package. Skip.
PYO3_PYTHON, PYTHONHOME, LD_LIBRARY_PATH - env vars for compiling PyO3 bindings against uv-managed Python. The wheel’s bindings are precompiled. Skip.
Postgres + pgadmin Docker compose - for Nautilus core’s persistence test suite. Cortana spike runs in-memory; M3 production uses Redis only. Skip.
Cranelift backend / nightly Rust - IDE/build speedup for contributors. Skip.
PyCharm Professional / Cython extension - IDE recommendation for contributors editing .pyx files. Cortana edits .py only. Skip.

Python version pin

Per nautilus-getting-started.md: Python 3.12-3.14 on 64-bit Linux (Ubuntu 22.04+, glibc 2.35+), macOS 15.0+ ARM64, or Windows Server 2022+ x86_64. Wheels are published for each (Python × platform) cross.

For Cortana MK3 spike: Python 3.12 or 3.13. 3.14 is the bleeding edge; prefer 3.12 for stability. Verify with:

python --version  # should print 3.12.x or 3.13.x

If MK2’s working venv is on 3.11 or older, the spike’s fresh worktree must upgrade - uv venv --python 3.12 will fetch and pin the right interpreter.

uv vs plain pip

The developer guide is explicit: “uv is the preferred tool for handling all Python virtual environments and dependencies.” This is the one preference from this page that Cortana adopts.

Why uv over pip for the spike:

Faster - uv pip install resolves and downloads in parallel. Saturday-morning <10 min budget benefits from this.
Reproducible - uv venv pins the Python interpreter; uv pip install resolves against it deterministically.
One tool - venv creation + dep install + Python version management in one binary.
Already on Cody’s machine - MK2 uses uv; no new install required.

Plain pip works fine if uv is unavailable. The Nautilus install command is identical except for the prefix:

# uv (preferred)
uv pip install "nautilus_trader[ib]"
 
# plain pip (fallback, after activating a venv)
pip install "nautilus_trader[ib]"

There is no Nautilus-specific reason to prefer one over the other beyond speed. Both produce the same installed wheel.

Optional extras (the load-bearing choice for Saturday)

Per nautilus-getting-started.md, available extras at 2026-05-07 are:

Extra	Pulls	When Cortana needs it
`betfair`	Betfair adapter	Never
`docker`	Dockerized IB Gateway helper deps	Maybe (see below)
`ib`	Interactive Brokers adapter	Mandatory - IBKR is sole pricing+exec source
`polymarket`	Polymarket adapter	Never
`visualization`	Plotly + tearsheet rendering	Step 0.5 + Step 7 (Saturday)

The package extras list is not exhaustively documented on the getting-started page; the canonical list is in pyproject.toml of the repo. Per nautilus-getting-started.md line 51-52: extras include betfair, docker, ib, polymarket, visualization. Confirm at install time by reading uv pip show nautilus_trader or by trying optional extras defensively (an unknown extra raises a warning, not an error).

Notable extras that may exist but are unconfirmed for Cortana

databento - for the Databento data adapter. Spike Step 0.5 uses Databento for OPRA SPY backfill. May be installable as nautilus_trader[databento] OR as a separate databento PyPI package consumed by DatabentoDataLoader. Verify Saturday morning. If nautilus_trader[databento] doesn’t resolve, fall back to pip install databento (the standalone Databento Python SDK) and use nautilus_trader.adapters.databento against it.
redis - Redis client for the Cache + MessageBus backends. M3+ production needs this; the spike skips it. Likely installable as nautilus_trader[redis] if it exists, otherwise pip install redis separately works.

Combining extras

# Spike Step 1 (mandatory only)
uv pip install "nautilus_trader[ib]"
 
# Spike with backtest visualization (recommended for Step 7)
uv pip install "nautilus_trader[ib,visualization]"
 
# Spike with Databento for Step 0.5 (if the extra exists)
uv pip install "nautilus_trader[ib,databento,visualization]"

Saturday recommendation: install [ib,visualization] up front; add Databento via pip install databento if/when Step 0.5 actually starts. Don’t pre-install everything - fewer extras = faster install = lower “did pip hang?” anxiety on Saturday morning.

Rust toolchain (when actually required vs not)

This is the single most-confused topic in Nautilus install discussions. The honest answer:

When Rust is NOT required (Cortana MK3, all milestones M0-M5)

uv pip install nautilus_trader from PyPI - wheels are prebuilt, the .so extensions already statically link the Rust libs. No Rust on the machine. Confirmed verbatim in nautilus-rust.md line 23: “End-users pip install nautilus_trader - wheels are prebuilt; no Rust toolchain required at runtime.”
Writing strategies, actors, configs - all Python, all crosses the PyO3 boundary, no Rust authorship.
IBKR adapter usage - ships compiled in the wheel; Rust source lives in nautilus_trader/adapters/interactive_brokers/ (legacy Cython tree, not Rust crates).

When Rust IS required

Building Nautilus from source (this page’s audience).
Authoring a new venue adapter in Rust (e.g., a Rust UW WebSocket adapter - deferred per nautilus-rust.md, Codex would author).
Extending matching/parsing/codec hot paths in Rust crates.
Forking the IBKR adapter to patch it (unlikely; would be a maintenance burden).

For Cortana MK3 spike + M0-M5: paths 2-4 don’t apply. Path 1 doesn’t apply because we use the wheel.

Rust install command (for reference, NOT for the spike)

If a future Cortana milestone ever does need Rust (e.g., authoring a Rust UW adapter), this is the install:

curl https://sh.rustup.rs -sSf | sh
source "$HOME/.cargo/env"
# MSRV per nautilus-rust.md: Rust 1.95.0
rustup default stable
rustc --version  # should be >= 1.95.0

Do not run this on Saturday. If you accidentally install Rust during the spike, it’s harmless - just unused disk. No need to uninstall.

macOS specifics

Officially supported

macOS 15.0 (Sequoia) and later, ARM64 (Apple Silicon) - per nautilus-getting-started.md. Cody’s machine: confirmed in scope.
Intel macOS is NOT in the supported list. (Older Intel Macs would need to build from source - out of scope.)

macOS-specific gotchas

Apple Silicon wheels exist on PyPI. uv pip install on M-series Macs pulls the ARM64 wheel - no Rosetta, no compile.
No LD_LIBRARY_PATH needed. That export in the developer guide is Linux-only; macOS uses DYLD_LIBRARY_PATH and only when building from source. Spike skips both.
No clang lld install needed for end users (apt-get install clang lld is Linux-only and contributor-only).
Xcode Command Line Tools - likely already installed on Cody’s machine. If uv complains about missing cc during a sub-dep build, run xcode-select --install. Not expected for the wheel install.
Rosetta is not needed. Nautilus ARM64 wheels are native.
Homebrew is not required for the spike. (Contributors might use it for Cap’n Proto via brew install capnp, but the spike doesn’t need Cap’n Proto.)

macOS ARM64 install verification

python -c "import platform; print(platform.machine(), platform.processor())"
# expected: arm64 arm
file .venv/lib/python3.12/site-packages/nautilus_trader/core/*.so | head -3
# expected: Mach-O 64-bit dynamically linked shared library arm64

If file reports x86_64, you’re on a Rosetta’d Python - fix by reinstalling Python via uv venv --python 3.12 on a native shell.

Docker dev option

Per nautilus-getting-started.md line 73-74: “A self-contained Jupyter notebook server is available as a Docker image, no local setup required. This is the lowest-friction path for a first backtest.”

For Cortana MK3 spike: do NOT use the Docker dev image. Three reasons:

nautilus-howto-configure-live-trading.md forbids live trading in Jupyter - the asyncio event loop conflicts. Spike Step 4 wants paper IBKR live, which needs a standalone Python script.
The spike worktree pattern wants a real venv on disk. Docker isolates it from MK2’s worktree, but also from Cody’s editor and Codex handoffs.
Docker dev image is for the Nautilus tutorial backtest only. Step 2 (their hello-world backtest) could run in it, but Step 5 (Cortana strategy port) and Step 4 (paper IBKR) cannot.

The separate Docker image Cortana DOES use is Dockerized IB Gateway (per nautilus-howto-configure-live-trading.md and nautilus-ib.md). That’s not the Nautilus dev image; it’s the IBKR Gateway running in Docker as the broker connection target. Spike Step 1 doesn’t need it; Step 4 does.

Cortana MK3 implications

Saturday 2026-05-09 - Step 1 install (the only commands that matter)

# Fresh worktree, NOT in belo-horizonte
mkdir -p ~/conductor/workspaces/cortanaroi-mk2/nautilus-spike
cd ~/conductor/workspaces/cortanaroi-mk2/nautilus-spike
 
# Create venv on Python 3.12
uv venv --python 3.12
source .venv/bin/activate
 
# Install Nautilus + IBKR + visualization
uv pip install "nautilus_trader[ib,visualization]"
 
# Smoke test
python -c "import nautilus_trader; print(nautilus_trader.__version__)"

If [visualization] errors as unknown extra (the extras list may have shifted), drop it and re-run with just [ib]. Visualization is a Step 7 nice-to-have, not Step 1 mandatory.

Step 0.5 (Databento) - additional install

# After Step 1 completes
uv pip install databento  # standalone Databento SDK; nautilus has DatabentoDataLoader against it

If nautilus_trader[databento] resolves, prefer that - but the standalone package always works.

What NOT to install (defensive list)

No Rust toolchain. No curl https://sh.rustup.rs | sh. If something during the spike asks for cargo, it’s the wrong path.
No Cap’n Proto. No brew install capnp. Wheels handle this.
No cargo-binstall, no prek, no make install-tools. Those exist only in the contributor clone of nautilus_trader.
No git clone https://github.com/nautechsystems/nautilus_trader. The wheel install is from PyPI, not from a clone.
No uv sync --all-groups --all-extras. That command works only inside the cloned repo. The spike worktree uses uv pip install.
No make build-debug. Wheels are prebuilt.
No PYO3_PYTHON / PYTHONHOME / LD_LIBRARY_PATH env vars. Those are for compiling PyO3 bindings; the wheel’s bindings are precompiled.
No Postgres / pgadmin Docker compose. Cortana spike is in-memory.

M3 production additions (Redis only)

When Cortana M3 cuts over to production:

# Add Redis to the existing venv
uv pip install redis  # standalone; nautilus_trader uses it via CacheConfig

Plus the Redis server itself (Docker redis:7 image is fine). Per nautilus-howto-configure-live-trading.md: “The minimum supported Redis version is 6.2.”

M4+ multi-tenant (process-per-tenant)

Each tenant Python process needs its own venv only if dependency versions diverge per tenant - they don’t. M4 uses one shared venv, N processes spawned from it, each with a different TradingNodeConfig. No env-setup implications beyond the M3 baseline.

Saturday-morning friction points (most likely first)

Ranked by probability of biting at Step 1:

Reading the developer-guide page by accident instead of the getting-started page. The dev guide URL ranks high in Google for “nautilus install” - easy to land on and start running make install-tools. Mitigation: this brain page exists explicitly to route Saturday Cody back to nautilus-getting-started.md.
Wrong Python version. MK2’s existing venv may be 3.11; Nautilus requires 3.12+. uv venv --python 3.12 in the fresh worktree sidesteps this.
[ib] extra not pulling IBKR adapter. The ib_async (or ib_insync) sub-dep occasionally has install friction on macOS. Verify post-install: python -c "from nautilus_trader.adapters.interactive_brokers.factories import InteractiveBrokersLiveDataClientFactory; print('ok')".
Rosetta’d Python 3.12. If Cody installed Python via the Intel Homebrew earlier and never noticed, the venv will be x86_64 and the ARM64 wheel install fails. uv venv --python 3.12 should fetch a fresh ARM64 interpreter, sidestepping this.
[visualization] extra unknown. Extras list may have shifted between doc rev and PyPI rev. Drop and continue if it errors.
Stale uv version. Nautilus core pins uv==0.11.8. End-user install is more permissive but very old uv (<0.4.x) may misresolve modern wheel metadata. uv self update if pre-2026.

When this concept applies

Spike Saturday Step 1 (install + smoke test).
M3 production cutover (add Redis client lib).
Any time Cortana MK3 needs to spin up a fresh venv on a new machine (laptop replacement, cloud worker provisioning, CI).

When it breaks / does not apply

The page’s contributor scaffolding does not apply to Cortana under any milestone unless we fork Nautilus core (not planned).
If Cortana ever authors a Rust crate (e.g., custom UW adapter per nautilus-rust.md Path 3), then some of this page applies - but Codex would handle the Rust setup, not Cody.
For the Nautilus dev Docker image (Jupyter-in-container), use nautilus-getting-started.md instead - that’s the user-facing Docker option, not this page’s contributor compose stack.

Timeline

2026-05-07 | Cody - Filed during pre-spike concept mastery sweep batch 7 (developer guide).

CortanaROI Brain

Explorer

nautilus-dev-environment-setup