v1.0.0 to v2.0.0

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

- - nvidia

- - sdk

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

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

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

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