NautilusTrader 2.x 完整安装指南：平台支持、PyPI/私有源/源码构建与精度模式配置

NautilusTrader 2.x 完整安装指南：平台支持、PyPI/私有源/源码构建与精度模式配置

【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader

本篇技术指南以 NautilusTrader（基于 Rust 的高性能事件驱动交易引擎）官方安装文档为核心，系统讲解其在 Python 3.12–3.14 下的全部受支持安装路径：PyPI 预编译 wheel、Nautech Systems 私有包索引、从源码构建以及 GitHub Release 二进制。读者读完将掌握 2.x 版本线的正确安装姿势（含--pre参数的必要性）、本地 Rust 开发环境的完整搭建、构建产物供应链验证方法，以及核心值类型高精度/标准精度两种模式的选择与配置。

平台与版本支持范围

NautilusTrader 官方支持 Python 3.12–3.14，覆盖以下 64 位平台（在仓库的 python/pyproject.toml 中requires-python = ">=3.12,<3.15"，且.whl分类器明确声明了 3.12/3.13/3.14）：

注：NautilusTrader 在其他平台上可能也能运行，但只有上表所列平台会被开发者常规使用并在 CI 中测试。

Python 支持窗口与 CI 基线

项目遵循 Scientific Python SPEC 0 定义的 Python 支持窗口：每个 Python 次版本在首次发布后支持三年，支持通常在窗口结束后、替代 Python 版本通过兼容性检查后的第一个 NautilusTrader 版本中终止。CI 的持续覆盖来自项目构建所用的 GitHub Actions runner 镜像，各平台的基线策略如下：

• Linux (Ubuntu)：目前固定在ubuntu-22.04，以保持 glibc 2.35 兼容性（即使ubuntu-latest已向前推进）。
• macOS (ARM64)：构建运行在macos-latest上，因此支持范围跟随该 runner 镜像向前演进。
• Windows (x86_64)：目前固定在windows-2022以保持工具链稳定。

在 Linux 上，安装前请用ldd --version确认 glibc 版本为2.35 或更新。

推荐的包管理器：uv

项目强烈推荐使用 uv 包管理器配合"纯净"的 CPython 使用。Conda 等其他 Python 发行版可能可用，但不属于官方支持范围。仓库对 uv 版本也有明确约束：python/pyproject.toml的[tool.uv]段声明了required-version = ">=0.12,<0.13"，本地 uv 超出该范围时uv lock/uv sync会直接失败。此外该段还设置了exclude-newer = "7 days"的供应链冷却策略（详见后文"源码检出内的版本解析陷阱"）。

官方安装方式有两种：

1. 从 PyPI 或 Nautech Systems 包索引安装预编译二进制 wheel；
2. 从源码构建。

从 PyPI 安装

2.x 版本线必须使用--pre

当前文档对应NautilusTrader 2.x。PyPI 上不带任何参数的uv pip install nautilus_trader仍会解析到 1.x 版本线，而 1.x 与 2.x 的 Python API 并不互通，这会导致文档中的示例代码抛出ImportError和TypeError。仓库 python/pyproject.toml 显示当前项目版本为2.0.0rc5，即 2.x 以2.0.0rcN预发布版本号发布到 PyPI。

在 2.0.0 正式发布前，安装 2.x wheel 必须显式加--pre：

uv pip install --pre nautilus_trader

安装完成后务必确认版本号以2.开头：

python -c "import nautilus_trader; print(nautilus_trader.__version__)"

关于此命令有两点提醒：

• --pre是必需的，因为这些 wheel 属于预发布构建；但安装后的导入名仍然是nautilus_trader。
• 不建议在生产环境（如控制真实资金的实盘交易）使用发布候选版本。
• 该命令应在 NautilusTrader 源码检出目录之外执行：仓库根目录为可复现开发设置了exclude-newer的 uv 策略（python/pyproject.toml中exclude-newer = "7 days"），会过滤掉新发布的 wheel。在源码检出内请改用下文"从源码构建"章节的make build-debug。

当前的 wheel 目标为 Python 3.12–3.14。当你需要本地 Rust 改动、调试构建，或目标平台没有可用 wheel 时，请选择从源码构建。

稳定版 1.x wheel

省略--pre会安装最新的稳定版 1.x：

uv pip install nautilus_trader

1.x 安装无法运行本文档配套的示例代码。从 1.x 迁移到 2.x 的 API 差异详见仓库根目录的 MIGRATION_V2.md。

安装可视化等可选依赖（Extras）

需要基于 Plotly 的交互式绩效图表（tearsheets）与行情图时，安装visualizationextra：

uv pip install --pre "nautilus_trader[visualization]"

该 extra 在 python/pyproject.toml 的[project.optional-dependencies]中定义，具体包含pandas>=2.3.3,<4.0.0、plotly>=7.0.0,<8.0.0、kaleido>=1.3.0,<2.0.0与simplejson>=4.1.2,<5.0.0四个依赖，且均设定了版本上限以保障 API 稳定性。

从 Nautech Systems 包索引安装

Nautech Systems 包索引（packages.nautechsystems.io）遵循 PEP-503 简单索引规范，同时托管nautilus_trader的稳定版与开发版二进制 wheel，方便用户在正式发布前测试最新功能。

稳定版 wheel

稳定版 wheel 与 PyPI 上的官方发布一一对应，采用标准版本号。与 PyPI 相同，该索引上的最新稳定版仍属 1.x 线，因此要安装 2.x wheel 仍需加--pre。

安装最新稳定版：

uv pip install nautilus_trader --index-url=https://packages.nautechsystems.io/simple

提示：如果希望 uv 在索引不可用时自动回退到 PyPI，请改用--extra-index-url而不是--index-url。

开发版 wheel（develop / nightly）

主包索引会从nightly与develop两个分支持续发布开发版 wheel，让用户能提前测试新特性与修复。这一流程同时节省了构建算力，并提供了与 CI 管线中测试的二进制完全一致的产物，版本号遵循 PEP-440 规范：

• develop分支 wheel 使用版本后缀.devYYYYMMDD+run；
• nightly分支 wheel 在基础版本已是预发布时使用.devYYYYMMDD，否则使用aYYYYMMDD。

各平台开发版 wheel 的覆盖情况：

警告：不建议在生产环境（如控制真实资金的实盘交易）使用开发版 wheel。

uv 默认安装最新稳定版；添加--pre标志后才会考虑包括开发版在内的预发布版本。安装最新可用的预发布版本（含开发版 wheel）：

uv pip install nautilus_trader --pre --index-url=https://packages.nautechsystems.io/simple

同样地：安装后的导入名仍为nautilus_trader；请在源码检出之外执行该命令，以免仓库的exclude-newer策略过滤掉新发布的 wheel；需要本地 Rust 改动、调试构建或目标平台无 wheel 时改用源码构建。

查看可用版本

可通过命令行以编程方式列出索引上的全部可用版本：

curl -s https://packages.nautechsystems.io/simple/nautilus-trader/index.html | grep -oP '(?<=<a href=")[^"]+(?=")' | awk -F'#' '{print $1}' | sort

分支更新与保留策略

• develop分支 wheel（.devYYYYMMDD+run）：每次合并提交都会持续构建并发布，仅保留最近一次构建。
• nightly分支 wheel（.devYYYYMMDD或aYYYYMMDD）：每天在14:00 UTC自动合并develop分支时（若有变更）构建发布，每个平台仅保留最近 30 个发布日期的 wheel。

构建来源（Provenance）验证

项目发布的所有产物都带有 CI/CD 管线生成的加密证明（attestation）：

• Python wheel 与 sdist（PyPI、GitHub Releases、Nautech Systems 包索引）：携带 SLSA 构建来源证明；
• Docker 镜像（ghcr.io/nautechsystems/nautilus_trader、ghcr.io/nautechsystems/jupyterlab）：携带无密钥 cosign 签名以及 SPDX SBOM 证明。

两者均通过 Sigstore 签发，并绑定到特定 commit SHA。验证通过即可确认产物由官方 NautilusTrader GitHub Actions 工作流生成、且自发布后未被篡改。分步验证命令见仓库根目录的 SECURITY.md。验证 Python 产物需要 GitHub CLI（gh），验证 Docker 镜像需要cosign；develop与nightly分支的开发版 wheel 同样带有证明。

从源码构建

当需要本地 Rust 改动、调试构建或目标平台没有预编译 wheel 时，可通过 pip 从源码安装，前提是先安装pyproject.toml中指定的构建依赖。完整流程如下。

1. 安装 rustup

安装 Rust 工具链管理器 rustup：

curl https://sh.rustup.rs -sSf | sh

# 从 https://win.rustup.rs/x86_64 下载并安装 rustup-init.exe # 同时通过 Visual Studio 2022 Build Tools 安装 "Desktop development with C++"

验证：rustc --version

仓库通过 rust-toolchain.toml 将 Rust 工具链固定在channel = "1.98.1"，保证所有贡献者与 CI 使用完全一致的编译器版本。

2. 启用 cargo

在当前的 shell 中启用cargo：

source $HOME/.cargo/env

# 开启一个新的 PowerShell 会话

3. 安装 clang

安装 clang（LLVM 的 C 语言前端）。在 Linux 上这会同时安装 lld（LLVM 链接器），仓库已将其配置为 Rust 链接器以加速构建：

sudo apt-get install clang lld

# 1. 通过 Visual Studio Installer 添加 Clang： # Modify > C++ Clang tools for Windows (latest) > Modify # 2. 添加到 PATH： [System.Environment]::SetEnvironmentVariable('path', "C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Tools\Llvm\x64\bin\;" + $env:Path,"User")

验证：clang --version。clang 是项目构建的默认编译器（Makefile 中CC ?= clang、CXX ?= clang++），部分依赖（如ed25519-blake2b）强制要求 clang。

4. 安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

irm https://astral.sh/uv/install.ps1 | iex

5. 克隆仓库并同步依赖

git clone --branch develop --depth 1 https://gitcode.com/GitHub_Trending/na/nautilus_trader cd nautilus_trader make sync

• --depth 1仅获取最新一次提交，克隆更快更轻量。
• 开发主机与 CI runner 镜像所需的全部工具版本都以仓库清单为准（单一版本来源），详见 docs/developer_guide/environment_setup.md。例如 Rust 版本来自 rust-toolchain.toml、Python 依赖与 uv 范围来自 python/pyproject.toml、精确解析来自python/uv.lock。
• make sync会校验本地 uv 版本是否符合python/pyproject.toml中的required-version范围，再执行uv sync --all-groups --all-extras --no-install-package nautilus-trader同步全部依赖（本包自身由 maturin 构建）。

6. 为开发安装 Cap'n Proto

如果你计划启用capnpRust 特性、重新生成序列化 schema 或从事序列化相关开发，需要安装 Cap'n Proto。在 Linux 或 macOS 上，使用仓库脚本安装.nautilus-engineering/tools.toml中固定的版本：

./scripts/install-capnp.sh

验证：capnp --version

注：Cap'n Proto 属于开发依赖，安装预编译 wheel 时并不需要。

7. 设置环境变量

uv 项目环境位于python/.venv（与python/pyproject.toml相邻）。请在python/目录下运行直接的 uv 项目命令，或在仓库根目录传入--project python。

在make sync之后、于 Bash 或 Zsh 中从仓库根目录运行以下命令（Linux 与 macOS 需要），为 PyO3 编译设置环境变量；Fish 命令见 docs/developer_guide/environment_setup.md：

# 为 PyO3 设置 Python 可执行文件路径 export PYO3_PYTHON="$PWD/python/.venv/bin/python" # 仅 Linux：设置 uv 托管 Python 运行时的库路径 PYTHON_LIB_DIR="$("$PYO3_PYTHON" -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))')" export LD_LIBRARY_PATH="$PYTHON_LIB_DIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" # 运行 Rust 测试所需（使用 uv 安装的 Python 时） export PYTHONHOME="$("$PYO3_PYTHON" -c 'import sys; print(sys.base_prefix)')"

各变量作用说明：

• PYO3_PYTHON告诉 PyO3 使用哪个 Python 解释器，可避免不必要的重编译；每个 shell 都应指向本检出的python/.venv/bin/python（若此前有指向根目录.venv/bin/python的 export，请替换掉）。
• LD_LIBRARY_PATH仅 Linux 需要，macOS 不需要。
• PYTHONHOME在使用 uv 安装的 Python 运行make cargo-test时必须设置，否则依赖 PyO3 的测试可能无法定位 Python 运行时。

8. 从源码构建 Python 包

该路径从python/目录构建 PyO3 包，并将其安装到python/.venv。当你的平台没有开发版 wheel、或需要本地 Rust 改动时使用。从仓库根目录执行：

make build-debug

该目标会：同步python/.venv→ 用 maturin 构建 Rust 扩展（Cargo 产物位于target/）→ 重新生成 Python 类型存根（stubs）。python/pyproject.toml的构建后端固定为maturin==1.15.0，maturin 配置中的manifest-path = "../crates/pyo3/Cargo.toml"指向 crates/pyo3 crate，module-name = "nautilus_trader._libnautilus"。

构建完成后，用项目环境运行一个 Python 示例：

uv run --project python --no-sync python examples/live/lighter/data_tester.py

该脚本会连接 Lighter 测试网并开始流式接收行情数据，按 Ctrl+C 停止。示例源码见 examples/live/lighter/data_tester.py。更多直接命令与测试目标见 python/README.md。

从 GitHub Release 安装

需要从 GitHub 安装二进制 wheel 时，先进入最新 release 页面，下载与你操作系统及 Python 版本匹配的.whl文件，然后运行：

uv pip install <file-name>.whl

常见问题排查（Troubleshooting）

文档示例无法导入

典型报错：

ImportError: cannot import name 'OrderSide' from 'nautilus_trader.model' ImportError: cannot import name 'BacktestEngine' from 'nautilus_trader.backtest' TypeError: Struct types cannot define __init__

这些错误源于用 1.x 安装运行 2.x 文档示例。先检查当前安装的版本：

python -c "import nautilus_trader; print(nautilus_trader.__version__)"

如果输出以1.开头，说明解析器选中了稳定版线，请用--pre重装：

uv pip install -U --pre nautilus_trader

1.x 与 2.x 的 Python API 不可互换，迁移 1.x 应用时请参考 MIGRATION_V2.md。

uv 在仓库内解析到旧版本

仓库根目录为可复现开发设置了exclude-newer策略（python/pyproject.toml 中exclude-newer = "7 days"），会隐藏近期发布的 wheel。请在其他目录执行安装命令，或改用从源码构建。该冷却策略的作用是给社区留出时间发现并隔离被投毒的版本，其值支持 RFC 3339 时间戳（如"2026-03-30T00:00:00Z"）、友好时长（如"7 days"）或 ISO 8601 时长（如"P7D"）。

找不到对应平台的 wheel

检查你的 Python 版本是否为 3.12–3.14，平台是否在本页顶部的支持列表内。在 Linux 上，ldd --version必须报告 glibc 2.35 或更新版本。否则请从源码构建。

版本管理与发布节奏

NautilusTrader 仍处于积极开发阶段：部分功能可能尚不完整，API 正趋于稳定但仍可能发生破坏性变更。项目会尽力在 release notes 中记录这些变更。官方目标为双周发布节奏，但实验性或较大型的功能可能导致延迟。使用 NautilusTrader 前请确认你能接受 API 演进带来的适配工作。

可选组件：Redis

仅在将 Redis 配置为缓存数据库或消息总线的后端时才需要安装 Redis。最低支持版本为6.2（因 streams 功能需要）。快速搭建推荐使用 Docker 容器，仓库的.docker目录提供了示例配置（见 .docker/docker-compose.yml，其中包含 postgres、redis、pgadmin 三个开发服务），也可以直接运行：

docker run -d --name redis -p 6379:6379 redis:latest

该命令会：

• 若本地未下载则从 Docker Hub 拉取最新版 Redis；
• 以分离模式（-d）运行容器；
• 将容器命名为redis便于引用；
• 将 Redis 暴露在默认端口 6379，使本机上的 NautilusTrader 可以访问。

容器管理：docker start redis启动、docker stop redis停止。可使用 Redis Insight 作为 GUI 可视化与调试 Redis 数据。

精度模式（Precision Mode）

NautilusTrader 的核心值类型（Price、Quantity、Money）支持两种精度模式，二者的内部位宽与最大十进制精度不同：

• 高精度（High-precision）：128 位整数，最多 16 位小数精度，值范围更大。
• 标准精度（Standard-precision）：64 位整数，最多 9 位小数精度，值范围更小。

注：官方 Python wheel 默认在所有受支持平台上以高精度（128 位）模式发布。对纯 Rust crate 而言，由于 Rust 通过软件模拟处理i128/u128，高精度可在所有平台（含 Windows）工作；默认是标准精度，除非显式启用high-precision特性。

性能权衡方面：标准精度在典型回测中约快 3–5%，但小数精度更低、可表示值范围更小（官方文档注明两种模式的性能基准对比尚在准备中，具体数据请以仓库后续发布的基准为准）。

构建配置

精度模式在编译期通过high-precisionRust 特性标志选择。Python 包在 maturin 构建特性中启用了该标志（见 python/pyproject.toml 的[tool.maturin] features列表，其中包含high-precision、extension-module、arrow、redis、postgres等），因此源码构建默认即为高精度。若需要标准精度（64 位）的 Python 构建，从 maturin 特性列表移除high-precision后照常构建：

make build-debug

Rust 特性标志

要在 Rust 中启用高精度（128 位）模式，在Cargo.toml中添加high-precision特性：

[dependencies] nautilus-core = { version = "*", features = ["high-precision"] }

从源码结构可以进一步印证该机制的传导关系：特性在 crates/model/Cargo.toml 中定义（high-precision = []），而defi特性因 DeFi 领域模型需要 18 位 wei 精度而隐式依赖high-precision；绝大多数交易所适配器（如 binance、bitmex、bybit、coinbase 等，见 crates/adapters/binance/Cargo.toml 等）也将high-precision设为默认特性并透传到nautilus-model。这也解释了为什么官方的预编译 wheel 默认就是高精度构建。更多值类型规范详见 docs/concepts/overview.md。

安装完成后的下一步

安装验证通过后，可参考 docs/getting_started/index.md 的引导继续推进：

• 五分钟快速上手回测：运行 docs/getting_started/quickstart.py，使用合成数据完成第一个回测，无需任何数据下载与 catalog 配置；
• 回测 API 两级抽象：低级 API 从BacktestEngine入手（见 docs/getting_started/backtest_low_level.py），高级 API 使用BacktestNode（见 docs/getting_started/backtest_high_level.py），后者面向生产工作流、更易过渡到实盘；高级 API 需要基于 Parquet 的数据 catalog，低级 API 支持内存数据但无实盘路径；
• 实盘交易：参考 docs/how_to/configure_live_trading.md 与 docs/integrations/ 中受支持的交易所集成；
• 免本地安装的 Docker 方案：拉取ghcr.io/nautechsystems/jupyterlab:nightly镜像（docker pull ghcr.io/nautechsystems/jupyterlab:nightly --platform linux/amd64）后运行docker run -p 8888:8888 ghcr.io/nautechsystems/jupyterlab:nightly，浏览器访问http://localhost:8888即可体验自带 Jupyter 服务器的完整环境（注意示例使用LoggerConfig(stdout_level=LogLevel.ERROR)以规避 Jupyter 的 stdout 速率限制）；该镜像与 .docker/nautilus_trader.dockerfile 一样采用 digest 固定的多阶段构建以保证供应链安全。

【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader