nixl

环境要求

• Linux 环境下的 C++ 构建工具链（meson、ninja、编译器）
• uv（即使已有其他 Python 虚拟环境管理器也必须安装）
• tomlkit Python 包
• PyTorch（按官网说明安装对应版本）
• CUDA 12 或 CUDA 13 环境（用于编译对应平台的 nixl-cu12 / nixl-cu13 包）

安装与启动步骤

1. 1克隆仓库

   从 GitHub 拉取 NIXL 源码，后续所有构建命令都在仓库根目录执行。

   git clone https://github.com/ai-dynamo/nixl.git
   cd nixl

   复制

2. 2安装 uv 与依赖

   先装 uv 并加入 PATH，再创建 Python 3.12 虚拟环境并安装 tomlkit。

   curl -LsSf https://astral.sh/uv/install.sh | sh
   export PATH="$HOME/.local/bin:${PATH}"
   uv venv .venv --python 3.12
   source .venv/bin/activate
   uv pip install tomlkit

   复制

3. 3安装 PyTorch

   按 PyTorch 官网给出的本地安装方式装好与本机 CUDA 匹配的 PyTorch，README 未固定版本。

4. 4构建安装主库

   用 meson 配置构建目录，ninja 编译并将 NIXL 二进制安装到系统前缀。

   pip install .
   meson setup build
   ninja -C build install

   复制

5. 5装 CUDA 平台包

   CUDA 12 直接走默认流程；CUDA 13 需先用 tomlutil 把 wheel 名改为 nixl-cu13。

   pip install build/src/bindings/python/nixl-meta/nixl-*-py3-none-any.whl

   复制

6. 6验证导入

   创建 nixl_agent 实例，看是否打印 UCX 后端实例化与 agent 初始化日志。

   python3 -c "import nixl; agent = nixl.nixl_agent('agent1')"

   复制

7. 7跑两节点示例

   先起 target 进程再起 initiator 进程，本地回环地址 127.0.0.1 端口 4242 传数据。

   python3 examples/python/expanded_two_peers.py --mode=target --use_cuda=true --ip=127.0.0.1 --port=4242 &
   sleep 5
   python3 examples/python/expanded_two_peers.py --mode=initiator --use_cuda=true --ip=127.0.0.1 --port=4242

   复制

8. 8构建容器镜像

   可选：在仓库根目录构建预装 Python 绑定的镜像，默认 Ubuntu 24.04。

   ./contrib/build-container.sh

   复制

关键配置

如何确认成功

执行 python3 -c "import nixl; agent = nixl.nixl_agent('agent1')" 后输出 Backend UCX was instantiated 与 Initialized NIXL agent

常见问题

注意事项

• README 中 meson setup 的构建目录名为占位符，示例统一用 build，可自行改名但后续 ninja -C 路径要同步修改。
• ninja install 完成后，文档会放在安装前缀的 share/doc/nixl/ 目录下。
• 容器镜像默认基于 Ubuntu 24.04，可用 --os ubuntu22 切换到 Ubuntu 22.04。
• 容器内已预装基于自身 PyTorch 源码编译的 Python 绑定，需要可分发的 wheel 时改用 wheel 构建脚本或已发布的 nixl 包。