⚡

HoloscanSDK安装向导Skill holoscan-setup

该技能用于引导Holoscan SDK的安装：检查主机硬件、操作系统、CUDA驱动和现有工具，评估平台兼容性，推荐合适的安装方法（NGC容器、Debian/apt、pip wheel、Conda或源码），并委派给对应的安装技能。关键词：Holoscan、SDK安装、NGC容器、Debian/apt、pip wheel、Conda、源码安装、平台兼容性、CUDA变体、GPU直通、Jetson、IGX、RHEL、Ubuntu。

其他 0 次安装 0 次浏览 更新于 9/7/2026
名称 holoscan-setup
版本 “1.0.0”
描述 “指导Holoscan SDK安装：检查主机，评估平台兼容性，推荐安装方法，并委派给匹配的安装技能。”
开源协议 Apache-2.0 metadata:
作者 “Holoscan Team holoscan-team@nvidia.com” github-url: “https://github.com/nvidia-holoscan/holoscan-sdk” tags: - holoscan - 安装 - nvidia - sdk - 设置

Holoscan SDK 安装设置

目的

通过检查硬件、操作系统、CUDA驱动和现有工具来确定当前主机正确的Holoscan SDK安装方法，然后委派给特定于方法的安装技能。涵盖Ubuntu、RHEL、IGX Orin、Jetson和DGX Spark / Grace-Hopper平台上的NGC容器、Debian/apt、pip wheel、Conda和源码构建。

前提条件

  • Linux主机（Ubuntu 22.04/24.04、RHEL 9.x、IGX Orin、Jetson或DGX Spark / Grace-Hopper）
  • 带有可用驱动程序的NVIDIA GPU（nvidia-smi返回CUDA版本）
  • 能够访问docs.nvidia.com和NGC
  • 选择的方法所需之一：Docker + NVIDIA容器工具包、apt、Python 3.10–3.13及pip、Conda或构建工具链

可用脚本

脚本 用途 参数
scripts/check_conda.sh 检测Conda安装，即使不在PATH中（搜索~/miniconda3、~/miniforge3、~/anaconda3、~/mambaforge、/opt/conda和shell rc文件）；报告env以及哪些env可以导入holoscan。 无
scripts/check_ngc_image.sh 检查给定CUDA标签后缀的NGC Holoscan容器镜像是否已拉取或可用。 <cuda-tag-suffix> — 为cuda13、cuda12-dgpu、cuda12-igpu之一

使用run_script("scripts/check_conda.sh")和run_script("scripts/check_ngc_image.sh", "cuda13")调用脚本。请信任脚本输出，而非which conda或docker images等裸命令。

说明

要对话式、逐步进行——不要一次性加载所有信息。完成每一步并回复后再进行下一步。

工作流规则（必须遵循）

  1. 在步骤5结尾处给出一行加粗建议，指明方法（例如 **建议：** NGC容器——捆绑所有依赖，最快获得可用安装。）。
  2. 对于具有Docker可用受支持x86_64主机的首次用户，该建议必须是NGC容器。
  3. 在建议之后，停止并询问要使用哪种方法。该轮不要粘贴docker pull、docker run、apt install、pip install或其他安装命令——这些属于步骤6中委派的安装技能。
  4. 如果涉及容器路径，请在步骤4中自行验证Docker + GPU直通（运行那里显示的命令）。不要要求用户为你运行nvidia-smi或docker --version。

第1步：先阅读文档

获取https://docs.nvidia.com/holoscan/sdk-user-guide/，然后是sdk_installation.html，以获得当前版本支持的平台、软件包名称和安装要求。不要依赖硬编码假设。

第2步：检查机器

并行运行：

uname -a && (lsb_release -a 2>/dev/null || cat /etc/os-release)
uname -m
nvidia-smi 2>&1 | head -10
nproc && free -h | head -2

关键： 从nvidia-smi（表头右上）读取"CUDA Version"字段——这是驱动程序支持的最大CUDA版本，并决定cuda12还是cuda13包选择。

第3步：评估兼容性

平台 可用方法
Ubuntu 22.04/24.04, x86_64 容器、Debian/apt、pip wheel、Conda、源码
RHEL 9.x, x86_64 仅容器
IGX Orin (ARM64) 容器、Debian/apt、源码
Jetson AGX Orin / Orin Nano 容器、Debian/apt (iGPU)
Jetson AGX Thor 容器、Debian/apt
DGX Spark / Grace-Hopper 容器（检查文档了解OS要求）
其他 Linux, x86_64 容器可能可行；如果glibc ≥ 2.35则可以使用pip wheel

第4步：检查工具并呈现选项

并行运行：

docker --version 2>&1 | head -1; python3 --version 2>&1; pip3 --version 2>&1
dpkg -l | grep holoscan || true
pip3 show holoscan 2>/dev/null | grep -E "^(Name|Version)" || true
~/holoscan/venv/bin/pip show holoscan 2>/dev/null | grep -E "^(Name|Version)" | sed 's/^/venv: /' || true

然后自行验证GPU直通——不要让用户运行这个：

docker run --rm --gpus all ubuntu:22.04 nvidia-smi 2>&1 | tail -5 || true

解读第5步状态列的结果：

  • docker 缺失 → 容器行状态 ✗ — 未安装Docker。
  • Docker存在但出现could not select device driver "nvidia" → ✗ — 缺少NVIDIA容器工具包。
  • 出现nvidia-smi输出 → ✓。

然后通过run_script调用检测脚本：

  • run_script("scripts/check_conda.sh") — 参见上面的“可用脚本”，了解为什么优先于conda --version。
  • run_script("scripts/check_ngc_image.sh", "<cuda-tag-suffix>") — 用第2步确定的标签替换<cuda-tag-suffix>（例如cuda13、cuda12-dgpu、cuda12-igpu）。

如果已经安装了Holoscan，请注明版本并询问是升级还是验证现有安装。

CUDA变体规则（规范参考——在以下所有步骤中应用）：

nvidia-smi CUDA版本 原生包 容器标签
13.x+ holoscan-cu13 / holoscan-cuda-13 cuda13
12.x, Blackwell GPU holoscan-cu12 / holoscan-cuda-12 cuda13 (向前兼容) 或 cuda12-dgpu
12.x, Ampere/Ada dGPU holoscan-cu12 / holoscan-cuda-12 cuda12-dgpu
ARM64 iGPU (Jetson, IGX) holoscan cuda12-igpu

原生安装将驱动程序CUDA版本视为硬上限。容器支持向前兼容（显示"CUDA Forward Compatibility mode ENABLED"横幅是预期，而非错误）。

第5步：呈现选项并建议

始终在表格中呈现所有方法——绝不省略行。使用状态列指示主机上的可用性（不可用的方法以✗及简短原因显示）。使用此表格式：

方法 最适合 状态
NGC容器 捆绑所有依赖（CUDA、TensorRT、LibTorch、ONNX Runtime、Vulkan）；C++ + Python。需要Docker + NVIDIA容器工具包。 ✓/✗ 基于docker存在性
Debian/apt 原生Ubuntu；仅C++ ✓/✗ 是否安装了包
pip wheel 仅Python项目；需要CUDA工具包在PATH中；Python 3.10–3.13。 ✓/✗ 是否在~/holoscan/venv虚拟环境中安装了wheel
Conda 仅CUDA 13；如果已在conda环境中则很好。 ✓/✗ 基于check_conda.sh输出（不仅是which conda）
源码 修改SDK内部、自定义CMake标志、调试符号、不支持的平台或未发布分支。 ✓/✗ 是否已克隆到~/holoscan/holoscan-sdk

在表格之后，以以下两行形式结束该轮：

建议： <方法> — <一行理由>

您想使用哪种方法？ (容器 / apt / wheel / conda / 源码)

如果用户是Holoscan新手且主机是受支持的x86_64平台且Docker可用，建议选择NGC容器。对于RHEL 9或其他仅容器主机，建议使用容器。对于无Docker主机上的纯Python项目，建议使用pip wheel。

不要在本轮中包含docker pull、docker run、apt install或pip install命令——这些属于步骤6中调用的安装技能。保持响应简短，以免表格中途被截断。

第6步：委派给安装技能

一旦选择方法，调用对应技能——不要内联重复安装步骤：

方法 要调用的技能
NGC容器 /holoscan-install-container
Debian/apt /holoscan-install-debian
pip wheel /holoscan-install-wheel
Conda /holoscan-install-conda
源码 /holoscan-install-source

将CUDA变体（cu12/cu13/igpu）和步骤2-4中的任何其他相关事实作为上下文传递，调用技能时带上。

安装技能拥有完整的命令集——包括推荐的容器标志（--gpus all、--ipc=host、--ulimit memlock=-1、--ulimit stack=67108864、内部ulimit -s 32768）和验证示例。不要从holoscan-setup中重述它们；委派并让安装技能产生它们。

第7步：总结

如果安装成功且测试已运行，打印测试结果的表格摘要。

限制

  • RHEL 9.x仅支持NGC容器方法——不发布原生包。
  • Conda包仅限CUDA 13；CUDA 12主机必须使用容器、apt、pip wheel或源码。
  • 自Holoscan v3.0.0起，Debian/apt仅安装C++；Python支持需要额外的pip wheel安装。
  • pip wheel需要glibc ≥ 2.35和Python 3.10–3.13。
  • 原生安装不能超过驱动程序报告的CUDA版本；只有容器可以使用CUDA向前兼容。
  • DGX Spark / Grace-Hopper的OS要求会在不同版本间变化——始终重新检查sdk_installation.html。

故障排除

  • conda --version显示"command not found"但已安装Conda — 常见于zsh设置中懒加载conda或仅.bashrc运行了conda init。使用run_script("scripts/check_conda.sh")；它会搜索安装目录和rc文件。
  • nvidia-smi显示的CUDA版本低于预期 — 该字段是驱动程序最大支持的CUDA，不是已安装工具包。在安装较新CUDA包前升级驱动程序。
  • Debian安装成功但Python中import holoscan失败 — 自v3.0.0起apt仅安装C++。请接着使用/holoscan-install-wheel。
  • pip install holoscan因glibc错误失败 — 主机glibc < 2.35。改用容器或apt。
  • check_ngc_image.sh报告镜像缺失 — 确认NGC登录（docker login nvcr.io）且标签后缀匹配第4步的CUDA变体规则。