Holoscan Setup

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

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

1. 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.).
2. For a first-time user on a supported x86_64 host with Docker available, that recommendation must be NGC Container.
3. 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.
4. 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:

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 vs cuda13 package selection.

Step 3: Assess Compatibility

Step 4: Check Tools and Present Options

Run in parallel:

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:

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

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