/holoscan-setup

name: holoscan-setup
version: "1.0.0"
description: "Guides Holoscan SDK installation: inspects the host, assesses platform compatibility, recommends an install method, and delegates to the matching install skill."
license: Apache-2.0
metadata:
  author: "Holoscan Team <holoscan-team@nvidia.com>"
  github-url: "https://github.com/nvidia-holoscan/holoscan-sdk"
  tags:
    - holoscan
    - installation
    - nvidia
    - sdk
    - 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

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

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

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

| 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 Recomm