⚡

HoloscanConda安装指南Skill holoscan-install-conda

本技能提供在 Linux x86_64 上通过 Conda 安装 NVIDIA Holoscan SDK v4.3+（CUDA 13 环境）的完整步骤，包括环境创建、Python/C++ 包安装、示例测试、常见问题处理。关键词：Holoscan，Conda 安装，CUDA 13，NVIDIA SDK，Python，C++，医疗影像，机器人。

0 次安装 1 次浏览 更新于 9/7/2026
名称 holoscan-install-conda
版本 “1.0.0”
描述 “通过 Conda 在 CUDA 13 环境中安装 Holoscan SDK v4.3+。适用于 Conda 安装；如果主机是 CUDA 12，请改走容器/wheel 安装。”
开源协议 Apache-2.0 metadata:
作者 “Holoscan Team holoscan-team@nvidia.com” github-url: “https://github.com/nvidia-holoscan/holoscan-sdk” tags: - holoscan - install - conda - cuda

Holoscan Conda 安装指南

目的

将 Holoscan SDK（Python 运行时和/或 C++ 开发头文件）安装到 Linux x86_64 上的 Conda 环境中，通过 conda-forge + rapidsai 渠道，并正确固定 CUDA 元包。

先决条件

  • Linux x86_64，配备 NVIDIA GPU 和 CUDA 13 驱动程序（用 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 符号链接及 holoscan-config.cmake，用于 find_package(holoscan)。
  • rmm — RAPIDS 内存管理器（rapidsai 渠道）。holoscan 的未声明运行时依赖；未安装则 import holoscan 失败。
  • ucxx — UCX Python 绑定（rapidsai 渠道），分布式/多进程应用需要。
  • cuda-version=13 — 固定 CUDA 13 元包版本，使求解器选取兼容的 CUDA 运行时库。

先创建环境：

source ~/miniforge3/etc/profile.d/conda.sh   # 仅当 conda 不在 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

# 修改 video_replayer.yaml —— 10 帧、无头模式。
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
  width: 854')
open('/tmp/video_replayer.yaml', 'w').write(c)
"

# hello_world —— 无需显示，无需数据；预期输出：“Hello World!”
python3 /tmp/hs_hello_world.py

# video_replayer —— 需要 racerx 数据；预期输出：渲染帧，“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   # 若 miniforge 以 -b 方式安装
conda activate holoscan
ulimit -s 32768   # 推荐 —— 可避免某些应用段错误

可考虑将这些行加入 ~/.bashrc 或 ~/.zshrc，以免重复输入。

然后提供后续步骤：

  • 查看 C++ 和 Python 示例：https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples
  • 逐步讲解某个示例：/explain-example
  • 开始构建自定义 Holoscan 应用

故障排查

  • ImportError: librmm.so: cannot open shared object file —— 未安装 rmm。请重跑第 2 步的 conda install 命令；rmm 是 holoscan 的未声明运行时依赖。
  • 求解器选到比预期旧的 holoscan 版本 —— 渠道顺序可能错误。请使用 -c rapidsai -c conda-forge（rapidsai 在前）；官方安装命令即此顺序。在严格渠道优先级模式下，若 conda-forge 在前会将求解器锁定到旧的 holoscan 构建。
  • 应用启动时段错误 —— 运行 Holoscan 应用前在当前 shell 中执行 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 文件。