holoscan-install-conda

Holoscan Conda 安装

用途

在 Linux x86_64 上，使用 conda-forge 和 rapidsai，以及正确固定版本的 CUDA 元包，将 Holoscan SDK（Python 运行时和／或 C++ 开发头文件）安装到 Conda 环境中。

先决条件

• 配备 NVIDIA GPU 和 CUDA 13 驱动的 Linux x86_64 系统（使用 nvidia-smi 检查）。
• conda（推荐使用 Miniforge）。如果尚未安装，第 1 步会安装。
• 可访问 conda-forge、rapidsai 和 docs.nvidia.com 的网络连接。

限制

• 仅支持 CUDA 13（自 v4.3.0 起——更早的版本使用 CUDA 12）。如果用户使用 CUDA 12 驱动，请改用 /holoscan-install-container 或 /holoscan-install-wheel。
• 仅支持 Linux x86_64；conda-forge 不支持 aarch64／iGPU。
• 建议在每个运行 Holoscan 的 shell 中设置 ulimit -s 32768；否则，某些应用可能会发生段错误。

第 0 步：查阅官方安装说明

安装前务必获取 https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html 中最新的 Conda 部分——软件包名称、渠道选择以及运行时／开发组件的划分可能随版本变化。具体请确认：

• 准确的运行时软件包名称（例如，用于 Python 绑定的 holoscan）。
• C++ 开发软件包的名称，以及用户是否需要它。从 v4.1.0 起，libholoscan-dev 是一个单独的软件包，包含头文件和 CMake 配置；用户需要开发 C++ 应用时务必安装。没有它，find_package(holoscan) 会失败，而且没有可供 #include 的头文件。
• 当前版本支持的 Python 版本（v4.3 支持 3.10–3.13）。
• 当前的 cuda-version 固定值（v4.3 → 13）。

rmm 和 ucxx 通过 rapidsai 渠道分发；holoscan、libholoscan 和 libholoscan-dev 来自 conda-forge。

如果文档与以下内容有出入，以文档为准——相应更新安装命令，并告知用户。

第 1 步：检查先决条件

conda --version 2>&1
nvidia-smi 2>&1 | head -5

如果找不到 conda，请静默安装 Miniforge（相比 Miniconda，优先选择它以使用 conda-forge）：

wget -q https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O /tmp/Miniforge3.sh
bash /tmp/Miniforge3.sh -b -p ~/miniforge3
source ~/miniforge3/etc/profile.d/conda.sh
conda --version

-b 标志可在非交互模式下安装，且不会修改 .bashrc。用户必须在每个新 shell 中运行 source ~/miniforge3/etc/profile.d/conda.sh（或将其添加到 shell RC 文件中），才能使用 conda。

第 2 步：创建环境并安装

软件包用途

• libholoscan — C++ 运行时符号（libholoscan_core.so）。会作为依赖项自动安装。
• holoscan — Python 绑定。
• libholoscan-dev — C++ 头文件、libholoscan_core.so 符号链接，以及用于 find_package(holoscan) 的 holoscan-config.cmake。
• rmm — RAPIDS Memory Manager（rapidsai 渠道）。这是 holoscan 未声明的运行时依赖；缺少它时，import holoscan 会失败。
• ucxx — UCX Python 绑定（rapidsai 渠道），分布式／多进程应用需要它。
• cuda-version=13 — 固定 CUDA 13 元包，以便求解器选择兼容的 CUDA 运行时库。

首先创建环境：

source ~/miniforge3/etc/profile.d/conda.sh   # if conda not yet on PATH
conda create -n holoscan python=3.13 -y
conda activate holoscan

然后根据用户的目标选择以下某个方案。

根据用户的目标选择软件包——仅使用 Python 时需要 holoscan，进行 C++ 开发时需要 libholoscan-dev，两者兼用时则同时安装：

conda install <packages> rmm ucxx cuda-version=13 -c rapidsai -c conda-forge -y

进行 C++ 开发时，还要安装工具链：

conda install -c conda-forge cxx-compiler cmake ninja -y

使用 python3 -c "import holoscan; print(holoscan.__version__)" 验证 Python 安装。使用 ls "$CONDA_PREFIX/include/holoscan" 验证 C++ 开发安装。

步骤 3：运行 Python 测试

建议执行 ulimit -s 32768，否则某些 Holoscan 应用可能会在启动时发生段错误。

video_replayer 是一个默认会无限循环的显示应用。请务必修改其 YAML，使其在 10 帧后停止（count: 10、repeat: false、realtime: false），并以无头模式运行（headless: true）。无头模式无论是否连接显示器都可运行，并能避免通过 SSH 连接时的 GUI 故障，因此无需根据 $DISPLAY 分支处理。

下载脚本和 YAML 配置，修改 YAML，然后运行：

source ~/miniforge3/etc/profile.d/conda.sh
conda activate holoscan
ulimit -s 32768

SDK_VER=$(python3 -c "import holoscan; print(holoscan.__version__)")
BASE="https://raw.githubusercontent.com/nvidia-holoscan/holoscan-sdk/v${SDK_VER}/examples"

curl -fsSL "${BASE}/hello_world/python/hello_world.py"         -o /tmp/hs_hello_world.py
curl -fsSL "${BASE}/video_replayer/python/video_replayer.py"   -o /tmp/hs_video_replayer.py
curl -fsSL "${BASE}/video_replayer/python/video_replayer.yaml" -o /tmp/video_replayer.yaml

# Patch video_replayer.yaml — 10 frames, headless.
python3 -c "
c = open('/tmp/video_replayer.yaml').read()
c = c.replace('count: 0', 'count: 10')
c = c.replace('repeat: true', 'repeat: false')
c = c.replace('realtime: true', 'realtime: false')
c = c.replace('  width: 854', '  headless: true\n  width: 854')
open('/tmp/video_replayer.yaml', 'w').write(c)"

# hello_world — no display, no data needed; expected: "Hello World!"
python3 /tmp/hs_hello_world.py

# video_replayer — needs racerx data; expected: frames rendered, "Graph execution finished."
HOLOSCAN_INPUT_PATH=/path/to/holoscan/data python3 /tmp/hs_video_replayer.py

HOLOSCAN_INPUT_PATH 必须指向包含 racerx/ 子目录的目录。如果用户有 SDK 源代码仓库，则该目录为 ~/repos/holoscan-sdk/data；否则，请使用 Debian 或源码安装目录中的 download_ngc_data 脚本下载。

步骤 4：提醒用户

用户必须在每个新的 shell 会话中执行以下操作：

source ~/miniforge3/etc/profile.d/conda.sh   # if Miniforge was installed with -b
conda activate holoscan
ulimit -s 32768   # recommended — prevents segfaults in some apps

可考虑将这些行添加到 ~/.bashrc 或 ~/.zshrc，以免反复执行。

然后提供后续步骤：

• 在 https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples 中探索 C++ 和 Python 示例
• 讲解特定示例：/explain-example
• 开始构建自定义 Holoscan 应用

故障排除

• ImportError: librmm.so: cannot open shared object file。 未安装 rmm。重新运行步骤 2 中的 conda install 命令——rmm 是 holoscan 未声明的运行时依赖项。
• Solver 选择的 holoscan 版本比预期旧。 Channel 顺序可能有误。请使用 -c rapidsai -c conda-forge（rapidsai 在前）——这是官方安装命令中的顺序；在严格的 channel 优先级下，如果 conda-forge 排在前面，solver 可能会锁定到较旧的 holoscan 版本。
• 应用启动时发生段错误。 在当前 shell 中运行任何 Holoscan 应用之前，先设置 ulimit -s 32768。并非所有应用都会触发此问题，但增大栈空间可以避免故障。
• 构建 C++ 应用时 find_package(holoscan) 失败。 请安装 libholoscan-dev（自 v4.1.0 起，头文件和 CMake 配置位于单独的软件包中）。
• 新 shell 中出现 conda: command not found。 Miniforge 使用 -b 安装，且未修改 .bashrc。请运行 source ~/miniforge3/etc/profile.d/conda.sh，或将其添加到 shell RC 文件中。