holoscan-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Holoscan SDK Setup

Holoscan SDK 安装设置

Purpose

目的

Determines the correct Holoscan SDK installation method for the current host by inspecting hardware, OS, CUDA driver, and existing tooling, then delegates to a method-specific install skill. Covers NGC container, Debian/apt, pip wheel, Conda, and source builds across Ubuntu, RHEL, IGX Orin, Jetson, and DGX Spark / Grace-Hopper platforms.

通过检查硬件、操作系统、CUDA驱动及现有工具，确定当前主机适用的Holoscan SDK正确安装方法，然后调用对应安装方法的专属技能。支持Ubuntu、RHEL、IGX Orin、Jetson和DGX Spark / Grace-Hopper平台上的NGC容器、Debian/apt、pip wheel、Conda及源码构建方式。

Prerequisites

前置条件

Linux host (Ubuntu 22.04/24.04, RHEL 9.x, IGX Orin, Jetson, or DGX Spark / Grace-Hopper)
NVIDIA GPU with a working driver (
```
nvidia-smi
```
returns a CUDA Version)
Network access to
```
docs.nvidia.com
```
and NGC
One of: Docker + NVIDIA Container Toolkit,
```
apt
```
, Python 3.10–3.13 with
```
pip
```
, Conda, or a build toolchain — depending on chosen method

Linux主机（Ubuntu 22.04/24.04、RHEL 9.x、IGX Orin、Jetson或DGX Spark / Grace-Hopper）
配备正常驱动的NVIDIA GPU（
```
nvidia-smi
```
可返回CUDA Version）
可访问
```
docs.nvidia.com
```
和NGC的网络权限
根据所选安装方法，需具备以下工具之一：Docker + NVIDIA Container Toolkit、
```
apt
```
、带
```
pip
```
的Python 3.10–3.13、Conda或构建工具链

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/check_conda.sh`	Detects Conda installs even when not on PATH (searches `~/miniconda3` , `~/miniforge3` , `~/anaconda3` , `~/mambaforge` , `/opt/conda` , and shell rc files); reports envs and which have `holoscan` importable.	none
`scripts/check_ngc_image.sh`	Checks whether the NGC Holoscan container image for a given CUDA tag suffix is pulled or available.	`<cuda-tag-suffix>` — one of `cuda13` , `cuda12-dgpu` , `cuda12-igpu`

Invoke scripts with

run_script("scripts/check_conda.sh")

and

run_script("scripts/check_ngc_image.sh", "cuda13")

. Trust the script output over bare commands such as

which conda

docker images

脚本	用途	参数
`scripts/check_conda.sh`	即使Conda不在PATH中也能检测到安装（搜索 `~/miniconda3` 、 `~/miniforge3` 、 `~/anaconda3` 、 `~/mambaforge` 、 `/opt/conda` 及shell配置文件）；报告环境信息及哪些环境可导入 `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

等原生命令。

Instructions

操作说明

Be conversational and step-by-step — do not front-load all the information. Complete each step and report back before moving on.

采用对话式、分步式流程——不要一次性提供所有信息。完成每一步并反馈后再进行下一步。

Workflow rules (must follow)

工作流规则（必须遵守）

End Step 5 with a bolded one-line recommendation that names the method (e.g.

**Recommendation:** NGC Container — bundles all deps, fastest path to a working install.

For a first-time user on a supported x86_64 host with Docker available, that recommendation must be NGC Container.
After the recommendation, stop and ask which method to use. Do not paste
```
docker pull
```
,
```
docker run
```
,
```
apt install
```
,
```
pip install
```
, or other install commands in that turn — those belong to the delegated install skill in Step 6.
If the container path is in play, verify Docker + GPU passthrough yourself in Step 4 (run the command shown there). Do not ask the user to run
```
nvidia-smi
```
or
```
docker --version
```
for you.

第5步结尾需给出加粗的单行推荐，明确安装方法（例如：

**推荐：** NGC容器 — 包含所有依赖项，是最快实现可用安装的路径。

）。

对于支持的x86_64主机且已安装Docker的首次用户，必须推荐NGC容器。
给出推荐后，暂停并询问用户选择哪种安装方法。此步骤不要粘贴
```
docker pull
```
、
```
docker run
```
、
```
apt install
```
、
```
pip install
```
等安装命令——这些命令属于第6步中调用的专属安装技能。
如果考虑使用容器路径，需在第4步自行验证Docker + GPU直通功能（运行此处所示命令）。不要让用户帮你运行
```
nvidia-smi
```
或
```
docker --version
```
。

Step 1: Read the Docs First

步骤1：先查阅文档

Fetch

https://docs.nvidia.com/holoscan/sdk-user-guide/

then

sdk_installation.html

to get the current release's supported platforms, package names, and install requirements. Do not rely on hardcoded assumptions.

获取

https://docs.nvidia.com/holoscan/sdk-user-guide/

中的

sdk_installation.html

，了解当前版本支持的平台、包名称及安装要求。不要依赖硬编码的假设。

Step 2: Inspect the Machine

步骤2：检查主机设备

Run in parallel:

bash

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

Key: Read the "CUDA Version" field from

nvidia-smi

(top-right of the table header) — this is the maximum CUDA version the driver supports, and drives

cuda12

cuda13

package selection.

并行运行以下命令：

bash

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

包。

Step 3: Assess Compatibility

步骤3：评估兼容性

Platform	Methods Available
Ubuntu 22.04/24.04, x86_64	Container, Debian/apt, pip wheel, Conda, Source
RHEL 9.x, x86_64	Container only
IGX Orin (ARM64)	Container, Debian/apt, Source
Jetson AGX Orin / Orin Nano	Container, Debian/apt (iGPU)
Jetson AGX Thor	Container, Debian/apt
DGX Spark / Grace-Hopper	Container (check docs for OS requirements)
Other Linux, x86_64	Container may work; pip wheel if glibc ≥ 2.35

平台	可用安装方法
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	容器（请查阅文档确认操作系统要求）
其他Linux，x86_64	容器可能可用；若glibc ≥ 2.35则可使用pip wheel

Step 4: Check Tools and Present Options

步骤4：检查工具并展示选项

Run in parallel:

bash

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

Then verify GPU passthrough yourself — do not ask the user to run this:

bash

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

Interpret the result for the Status column in Step 5:

```
docker
```
missing → container row Status
```
✗ — Docker not installed
```
.

Docker present but

could not select device driver "nvidia"

→

✗ — NVIDIA Container Toolkit missing

```
nvidia-smi
```
output appears →
```
✓
```
.

Then invoke the detection scripts via

run_script

```
run_script("scripts/check_conda.sh")
```
— see Available Scripts above for why this is preferred over
```
conda --version
```
.

run_script("scripts/check_ngc_image.sh", "<cuda-tag-suffix>")

— replace

<cuda-tag-suffix>

with the tag determined from Step 2 (e.g.

cuda13

cuda12-dgpu

cuda12-igpu

If Holoscan is already installed, note the version and ask whether to upgrade or verify the existing install.

CUDA variant rule (canonical reference — apply this in all steps below):

nvidia-smi CUDA Version	Native packages	Container tag
13.x+	`holoscan-cu13` / `holoscan-cuda-13`	`cuda13`
12.x, Blackwell GPU	`holoscan-cu12` / `holoscan-cuda-12`	`cuda13` (Forward Compat) or `cuda12-dgpu`
12.x, Ampere/Ada dGPU	`holoscan-cu12` / `holoscan-cuda-12`	`cuda12-dgpu`
ARM64 iGPU (Jetson, IGX)	`holoscan`	`cuda12-igpu`

Native installs treat the driver CUDA version as a hard ceiling. Containers support Forward Compatibility (banner saying "CUDA Forward Compatibility mode ENABLED" is expected, not an error).

并行运行以下命令：

bash

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直通功能——不要让用户运行此命令：

bash

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 Container Toolkit缺失

。

显示
```
nvidia-smi
```
输出 →
```
✓
```
。

然后通过

run_script

调用检测脚本：

```
run_script("scripts/check_conda.sh")
```
— 如上述可用脚本部分所述，此方法比
```
conda --version
```
更可靠。

run_script("scripts/check_ngc_image.sh", "<cuda-tag-suffix>")

— 将

<cuda-tag-suffix>

替换为步骤2中确定的标签（例如

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"提示为正常现象，并非错误）。

Step 5: Present Options and Recommend

步骤5：展示选项并给出推荐

Always present all methods in the table — never omit a row. Use the Status column to indicate availability on the host (unavailable methods show ✗ with a short reason). Use this table format:

Method	Best for	Status
NGC Container	All deps bundled (CUDA, TensorRT, LibTorch, ONNX Runtime, Vulkan); C++ + Python. Needs Docker + NVIDIA Container Toolkit.	✓/✗ based on docker presence
Debian/apt	Native Ubuntu; C++ only	✓/✗ if package is installed
pip wheel	Python-only projects; needs CUDA Toolkit on PATH; Python 3.10–3.13.	✓/✗ if wheel is installed in virtual env at ~/holoscan/venv
Conda	CUDA 13 only; good if already in a conda environment.	✓/✗ based on `check_conda.sh` output (not just `which conda` )
Source	Modifying SDK internals, custom CMake flags, debug symbols, unsupported platform, or unreleased branch.	✓/✗ if already cloned at ~/holoscan/holoscan-sdk

After the table, end the turn with this exact two-line shape:

Recommendation:
<method>
—
<one-line why>
Which method would you like to use? (container / apt / wheel / conda / source)

If the user is new to Holoscan and the host is a supported x86_64 platform with Docker available, recommend NGC Container. For RHEL 9 or other container-only hosts, recommend container. For Python-only projects on a Docker-less host, recommend pip wheel.

Do not include

docker pull

docker run

apt install

, or

pip install

commands in this turn — those live in the install skill invoked in Step 6. Keep this response short to avoid being truncated mid-table.

始终展示所有方法的表格——不要省略任何一行。使用状态列表示主机上的可用性（不可用方法显示✗及简短原因）。使用以下表格格式：

方法	适用场景	状态
NGC容器	包含所有依赖项（CUDA、TensorRT、LibTorch、ONNX Runtime、Vulkan）；支持C++ + Python。需要Docker + NVIDIA Container Toolkit。	根据Docker存在情况显示✓/✗
Debian/apt	Ubuntu原生环境；仅支持C++	根据包是否已安装显示✓/✗
pip wheel	仅Python项目；需要PATH中存在CUDA Toolkit；支持Python 3.10–3.13。	根据~/holoscan/venv虚拟环境中是否已安装wheel显示✓/✗
Conda	仅支持CUDA 13；适合已使用conda环境的用户。	根据 `check_conda.sh` 输出显示✓/✗（而非仅 `which conda` ）
源码构建	修改SDK内部代码、自定义CMake参数、调试符号、非支持平台或未发布分支。	根据~/holoscan/holoscan-sdk是否已克隆显示✓/✗

表格之后，以以下固定两行格式结束此步骤：

推荐：
<方法>
—
<单行理由>
你想使用哪种方法？（container / apt / wheel / conda / source）

如果用户是Holoscan新手且主机为支持的x86_64平台并已安装Docker，推荐NGC容器。对于RHEL 9或仅支持容器的主机，推荐容器方法。对于无Docker的仅Python项目主机，推荐pip wheel。

此步骤不要包含

docker pull

、

docker run

、

apt install

或

pip install

命令——这些命令属于第6步调用的安装技能。保持此回复简洁，避免表格被截断。

Step 6: Delegate to the Install Skill

步骤6：调用专属安装技能

Once a method is picked, invoke the corresponding skill — do not repeat the install steps inline:

Method	Skill to invoke
NGC Container	`/holoscan-install-container`
Debian/apt	`/holoscan-install-debian`
pip wheel	`/holoscan-install-wheel`
Conda	`/holoscan-install-conda`
Source	`/holoscan-install-source`

Pass the CUDA variant (cu12/cu13/igpu) and any other relevant facts from Steps 2–4 as context when invoking the skill.

The install skill owns the full command set — including the recommended container flags (

--gpus all

--ipc=host

--ulimit memlock=-1

--ulimit stack=67108864

, inner

ulimit -s 32768

) and verification examples. Do not restate them from

holoscan-setup

; delegate and let the install skill produce them.

用户选定方法后，调用对应技能——不要重复安装步骤：

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

调用技能时，传递步骤2-4中获取的CUDA变体（cu12/cu13/igpu）及其他相关信息作为上下文。

安装技能负责完整的命令集——包括推荐的容器参数（

--gpus all

、

--ipc=host

、

--ulimit memlock=-1

、

--ulimit stack=67108864

、内部

ulimit -s 32768

）及验证示例。不要在

holoscan-setup

中重复这些内容；直接调用安装技能即可。

Step 7: Summary

步骤7：总结

If installation was successful and tests were run, print a table summary of test results.

如果安装成功并完成测试，打印测试结果的表格总结。

Limitations

限制说明

RHEL 9.x supports the NGC container method only — native packages are not published.
Conda packages are CUDA 13 only; CUDA 12 hosts must use container, apt, pip wheel, or source.
Debian/apt installs C++ only since Holoscan v3.0.0; Python support requires an additional pip wheel install.
pip wheel requires glibc ≥ 2.35 and Python 3.10–3.13.
Native installs cannot exceed the driver's reported CUDA Version; only containers can use CUDA Forward Compatibility.
DGX Spark / Grace-Hopper OS requirements change between releases — always re-check
```
sdk_installation.html
```
.

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的操作系统要求随版本变化——请始终重新查阅
```
sdk_installation.html
```
。

Troubleshooting

故障排除

conda --version
says "command not found" but Conda is installed — common in zsh setups with lazy-loaded conda or when only
```
.bashrc
```
ran
```
conda init
```
. Use
```
run_script("scripts/check_conda.sh")
```
; it searches install dirs and rc files.
nvidia-smi
shows a lower CUDA Version than expected — that field is the driver's max supported CUDA, not the installed toolkit. Upgrade the driver before installing a newer-CUDA package.
Debian install succeeds but
import holoscan
fails in Python — apt installs C++ only since v3.0.0. Follow up with
```
/holoscan-install-wheel
```
.
pip install holoscan
fails with glibc errors — host glibc is < 2.35. Use container or apt instead.
check_ngc_image.sh
reports image missing — confirm NGC login (
```
docker login nvcr.io
```
) and that the tag suffix matches the CUDA variant rule in Step 4.

conda --version
提示"command not found"但已安装Conda — 在zsh环境中常见，可能是Conda延迟加载或仅
```
.bashrc
```
执行了
```
conda init
```
。使用
```
run_script("scripts/check_conda.sh")
```
；该脚本会搜索安装目录和配置文件。
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变体规则。