Holoscan SDK Setup

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.

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

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

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.

Step 1: Read the Docs First

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.

Step 2: Inspect the Machine

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.

Step 3: Assess Compatibility

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

Step 4: Check Tools and Present Options

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).

Step 5: Present Options and Recommend

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.

Step 6: Delegate to the Install Skill

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.

Step 7: Summary

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
```
.

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.

holoscan-setup

NPX Install

Tags

SKILL.md Content

Holoscan SDK Setup

Purpose

Prerequisites

Available Scripts

Instructions

Workflow rules (must follow)

Step 1: Read the Docs First

Step 2: Inspect the Machine

Step 3: Assess Compatibility

Step 4: Check Tools and Present Options

Step 5: Present Options and Recommend

Step 6: Delegate to the Install Skill

Step 7: Summary

Limitations

Troubleshooting