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操作系统支持版本CPU 架构Linux (Ubuntu)22.04 及更新版本x86_64Linux (Ubuntu)22.04 及更新版本ARM64macOS15.0 及更新版本ARM64Windows Server2022 及更新版本x86_64注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的供应链冷却策略详见后文源码检出内的版本解析陷阱。官方安装方式有两种从 PyPI 或 Nautech Systems 包索引安装预编译二进制 wheel从源码构建。从 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 必须显式加--preuv 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.xuv pip install nautilus_trader1.x 安装无法运行本文档配套的示例代码。从 1.x 迁移到 2.x 的 API 差异详见仓库根目录的 MIGRATION_V2.md。安装可视化等可选依赖Extras需要基于 Plotly 的交互式绩效图表tearsheets与行情图时安装visualizationextrauv pip install --pre nautilus_trader[visualization]该 extra 在 python/pyproject.toml 的[project.optional-dependencies]中定义具体包含pandas2.3.3,4.0.0、plotly7.0.0,8.0.0、kaleido1.3.0,2.0.0与simplejson4.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-urlhttps://packages.nautechsystems.io/simple提示如果希望 uv 在索引不可用时自动回退到 PyPI请改用--extra-index-url而不是--index-url。开发版 wheeldevelop / nightly主包索引会从nightly与develop两个分支持续发布开发版 wheel让用户能提前测试新特性与修复。这一流程同时节省了构建算力并提供了与 CI 管线中测试的二进制完全一致的产物版本号遵循 PEP-440 规范develop分支 wheel 使用版本后缀.devYYYYMMDDrunnightly分支 wheel 在基础版本已是预发布时使用.devYYYYMMDD否则使用aYYYYMMDD。各平台开发版 wheel 的覆盖情况平台DevelopNightlyLinux (x86_64)✓✓Linux (ARM64)-✓macOS (ARM64)-✓Windows (x86_64)-✓警告不建议在生产环境如控制真实资金的实盘交易使用开发版 wheel。uv 默认安装最新稳定版添加--pre标志后才会考虑包括开发版在内的预发布版本。安装最新可用的预发布版本含开发版 wheeluv pip install nautilus_trader --pre --index-urlhttps://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.devYYYYMMDDrun每次合并提交都会持续构建并发布仅保留最近一次构建。nightly分支 wheel.devYYYYMMDD或aYYYYMMDD每天在14:00 UTC自动合并develop分支时若有变更构建发布每个平台仅保留最近 30 个发布日期的 wheel。构建来源Provenance验证项目发布的所有产物都带有 CI/CD 管线生成的加密证明attestationPython wheel 与 sdistPyPI、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 CLIgh验证 Docker 镜像需要cosigndevelop与nightly分支的开发版 wheel 同样带有证明。从源码构建当需要本地 Rust 改动、调试构建或目标平台没有预编译 wheel 时可通过 pip 从源码安装前提是先安装pyproject.toml中指定的构建依赖。完整流程如下。1. 安装 rustup安装 Rust 工具链管理器 rustupcurl 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 中启用cargosource $HOME/.cargo/env# 开启一个新的 PowerShell 会话3. 安装 clang安装 clangLLVM 的 C 语言前端。在 Linux 上这会同时安装 lldLLVM 链接器仓库已将其配置为 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. 安装 uvcurl -LsSf https://astral.sh/uv/install.sh | shirm https://astral.sh/uv/install.ps1 | iex5. 克隆仓库并同步依赖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. 为开发安装 Capn Proto如果你计划启用capnpRust 特性、重新生成序列化 schema 或从事序列化相关开发需要安装 Capn Proto。在 Linux 或 macOS 上使用仓库脚本安装.nautilus-engineering/tools.toml中固定的版本./scripts/install-capnp.sh验证capnp --version注Capn 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的构建后端固定为maturin1.15.0maturin 配置中的manifest-path ../crates/pyo3/Cargo.toml指向 crates/pyo3 cratemodule-name nautilus_trader._libnautilus。构建完成后用项目环境运行一个 Python 示例uv run --project python --no-sync python examples/live/lighter/data_tester.py该脚本会连接 Lighter 测试网并开始流式接收行情数据按 CtrlC 停止。示例源码见 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_trader1.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 ModeNautilusTrader 的核心值类型Price、Quantity、Money支持两种精度模式二者的内部位宽与最大十进制精度不同高精度High-precision128 位整数最多 16 位小数精度值范围更大。标准精度Standard-precision64 位整数最多 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-debugRust 特性标志要在 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_levelLogLevel.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考