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

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:

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:

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.