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

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

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

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