holoscan-install-container · diff
v1.0.0 to v2.0.0
68 added, 123 removed. Audit A to A.
---
name: holoscan-install-container
- version: "1.0.0"
- description: "Install Holoscan SDK via the NGC Docker container. Use for container-based installs; not for native apt/pip/Conda installs."
+ description: "Install and verify the Holoscan SDK 5.x CUDA 13 development container after checking release availability and host compatibility."
license: Apache-2.0
metadata:
author: "Holoscan Team <holoscan-team@nvidia.com>"
+ version: "2.0.0"
github-url: "https://github.com/nvidia-holoscan/holoscan-sdk"
tags:
- holoscan
- - install
+ - installation
- container
- - docker
- - ngc
---
- # Holoscan NGC Container Installation
-
- ## Purpose
-
- Pull and verify the official Holoscan SDK container from NGC (`nvcr.io/nvidia/clara-holoscan/holoscan`), selecting the right CUDA/arch tag for the host GPU and validating with the bundled Python and C++ examples.
-
- ## Prerequisites
-
- - Linux host with an NVIDIA GPU and a working driver (`nvidia-smi`).
- - Docker installed and the user in the `docker` group (or `sudo`).
- - NVIDIA Container Toolkit installed (`docker run --gpus all` works).
- - ~10–20 GB free disk for the image pull.
- - Network access to `nvcr.io` and `docs.nvidia.com`.
-
- ## Limitations
-
- - Container images cover only the tag matrix below — no Conda/pip env inside.
- - GUI examples require X11 forwarding; this skill runs Holoviz headless to avoid that.
- - Tag suffix must match the host GPU/driver (cuda13 / cuda12-dgpu / cuda12-igpu) — wrong suffix → CUDA init failures.
-
- ## Instructions
+ # Holoscan 5.x Development Container
- - Container repo: `nvcr.io/nvidia/clara-holoscan/holoscan`.
- - The doc page at https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html is canonical — fetch it if anything below disagrees.
- - Work through the steps below in order: pick the tag, verify GPU passthrough and pull, verify with the six examples, then hand off the launch command.
+ ## 1. Check the release and platform
- ## Step 1: Pick the tag
+ This skill targets **Holoscan SDK 5.x**. Select the requested 5.x release before
+ choosing artifacts. Read its release notes and the matching
+ [SDK installation guide](https://docs.nvidia.com/holoscan/sdk-user-guide/setup/sdk-installation).
+ Select the 5.x documentation version; an unversioned page may describe 4.x.
+ For an unreleased checkout, use its `docs/sdk_installation.mdx` and `DEVELOP.md`.
+ Early Access binary commands describe planned artifacts, so confirm publication
+ for the exact release before installing. If unavailable, explain that status
+ and offer `holoscan-install-source`; keep the requested 5.x version.
- Tag = `<version>-<suffix>`, e.g. `v4.1.0-cuda13`. Get the current SDK version from the doc page above; pick the suffix from `nvidia-smi` (the "CUDA Version" field, top-right of the table header):
+ The 5.0 artifact set targets CUDA 13 and dGPU systems on x86_64 or arm64.
+ Native packages use Ubuntu 24.04; wheels use glibc 2.39 and regular CPython
+ 3.12–3.14. Check the selected release for changes to that matrix. There is no
+ CUDA 12 variant or separate Tegra/iGPU artifact in this set. A driver reporting
+ CUDA 12 support needs a compatibility assessment or driver upgrade before a
+ CUDA 13 installation; the `nvidia-smi` CUDA field is a driver capability, not
+ the installed toolkit version. Never infer compatibility from that field alone.
- | `nvidia-smi` CUDA Version | Suffix |
- |---|---|
- | 13.x+ | `cuda13` |
- | 12.x, Ampere/Ada dGPU | `cuda12-dgpu` |
- | 12.x, ARM64 iGPU (nvgpu) | `cuda12-igpu` |
+ ## 2. Select and pull the image
- The "CUDA Forward Compatibility mode ENABLED" banner is expected — not an error — when the container ships a newer CUDA minor version than the host driver supports. The forward-compat shim lets the container's CUDA runtime work against the older host driver within the same major version.
+ Inspect Linux architecture, GPU model, driver, Docker, and NVIDIA Container
+ Toolkit. The planned image is one multi-architecture amd64/arm64 dGPU image:
+ `nvcr.io/nvidia/clara-holoscan/holoscan:v<SDK_VERSION>-cuda13`.
+ Check the [NGC catalog](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan)
+ and release notes for the exact published tag and supported host. There are no
+ `cuda12-dgpu` or `cuda12-igpu` tags for this 5.x workflow. GPU passthrough tests
+ may pull an image; explain the download before running one if needed.
- ## Step 2: Verify GPU passthrough, then pull
+ Use the exact published tag within the installation scope the user authorized.
+ When the method and release are already selected, proceed with that choice.
+ Ask only when a missing release or host fact prevents safe selection.
+ For a plan-only request, return the commands without pulling or running images:
```bash
- docker run --rm --gpus all ubuntu:22.04 nvidia-smi 2>&1 | tail -5
+ # SDK_VERSION is the exact published 5.x tag version from the release notes.
+ IMAGE="nvcr.io/nvidia/clara-holoscan/holoscan:v${SDK_VERSION}-cuda13"
+ docker pull "$IMAGE"
+ docker image inspect --format 'ID={{.Id}} RepoDigests={{json .RepoDigests}}' "$IMAGE"
+ docker run --rm --gpus all "$IMAGE" nvidia-smi
```
- If Docker is missing → install from https://docs.docker.com/engine/install/. If GPU passthrough fails → install the NVIDIA Container Toolkit per https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html, then retry.
-
- Pull (~10–20 GB — warn the user before starting):
+ Record the image ID and repository digests from inspection for the final report.
+ If no repository digest is available, report the image ID and that limitation.
- ```bash
- docker pull nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>
- ```
+ The development image contains the installed C++ and Python SDK under `/usr`,
+ all three optional modules, examples, and RacerX data. It is distinct from the
+ source-build container managed by `./run`.
- ## Step 3: Verify with six examples
+ ## 3. Verify the installed SDK
- Tests cover: bare Python binding (1a), bare C++ runtime (1b, 2a), Python + Holoviz/Vulkan (2b, 3a), and C++ + Holoviz/Vulkan (3b). Holoviz examples always run headless (inject `headless: true` into the YAML) — this works whether or not a display is attached and avoids GUI failure modes over SSH.
+ Use a bounded Core example and Python API discovery first. Locate the examples
+ instead of assuming the 4.x `/opt/nvidia/holoscan` layout or a fixed multiarch
+ library directory:
```bash
- IMG=nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>
- RUN=(docker run --rm --runtime=nvidia --gpus all --cap-add CAP_SYS_PTRACE --ipc=host --ulimit memlock=-1 --ulimit stack=67108864)
-
- # 1a. hello_world (Python) — expect "Hello World!"
- "${RUN[@]}" "$IMG" bash -c \
- "ulimit -s 32768 && python3 /opt/nvidia/holoscan/examples/hello_world/python/hello_world.py"
-
- # 1b. hello_world (C++) — expect "Hello World!"
- "${RUN[@]}" "$IMG" bash -c \
- "ulimit -s 32768 && /opt/nvidia/holoscan/examples/hello_world/cpp/hello_world"
-
- # 2a. tensor_interop (C++) — expect tensors doubling each pass, "Graph execution finished."
- "${RUN[@]}" "$IMG" bash -c \
- "ulimit -s 32768 && /opt/nvidia/holoscan/examples/tensor_interop/cpp/tensor_interop"
-
- # 2b. tensor_interop (Python, 10 frames) — Holoviz, headless. The YAML has no
- # headless field by default, so inject one under `holoviz:`. Expect
- # "message received (count: 10)".
- "${RUN[@]}" "$IMG" bash -c "
- ulimit -s 32768
- sed -e 's/count: 0/count: 10/' \
- -e 's/repeat: true/repeat: false/' \
- -e 's/realtime: true/realtime: false/' \
- -e 's/^holoviz:/holoviz:\n headless: true/' \
- /opt/nvidia/holoscan/examples/tensor_interop/python/tensor_interop.yaml > /tmp/ti.yaml
- cd /opt/nvidia/holoscan/examples/tensor_interop/python
- python3 tensor_interop.py --config /tmp/ti.yaml
- "
-
- # 3a. video_replayer (Python, 10 frames) — Holoviz, headless. Inject `headless: true`
- # under `holoviz:` (above `width: 854`). Same sed works for the C++ YAML in 3b —
- # both files share the same `holoviz:` section shape.
- "${RUN[@]}" "$IMG" bash -c "
- ulimit -s 32768
- sed -e 's/count: 0/count: 10/' \
- -e 's/repeat: true/repeat: false/' \
- -e 's/realtime: true/realtime: false/' \
- -e 's/^ width: 854/ headless: true\n width: 854/' \
- /opt/nvidia/holoscan/examples/video_replayer/python/video_replayer.yaml > /tmp/vr.yaml
- cd /opt/nvidia/holoscan/examples/video_replayer/python
- HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data python3 video_replayer.py --config /tmp/vr.yaml
- "
-
- # 3b. video_replayer (C++, 10 frames) — same headless injection as 3a. The C++
- # YAML hard-codes `directory: "../data/racerx"`, but HOLOSCAN_INPUT_PATH
- # overrides it, so we don't need to patch that field.
- "${RUN[@]}" "$IMG" bash -c "
- ulimit -s 32768
- sed -e 's/count: 0/count: 10/' \
- -e 's/repeat: true/repeat: false/' \
- -e 's/realtime: true/realtime: false/' \
- -e 's/^ width: 854/ headless: true\n width: 854/' \
- /opt/nvidia/holoscan/examples/video_replayer/cpp/video_replayer.yaml > /tmp/vr_cpp.yaml
- cd /opt/nvidia/holoscan/examples/video_replayer/cpp
- HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data ./video_replayer --config /tmp/vr_cpp.yaml
- "
+ docker run --rm --gpus all "$IMAGE" bash -eu -c '
+ example=$(find /usr/lib -type f -path "*/holoscan/examples/hello_world/cpp/hello_world" -print -quit)
+ test -n "$example"
+ "$example"
+ python3 -c "import holoscan as hs; print(hs.__version__); print(hs.RealtimeClock); print(len(hs.registry.operators()))"
+ '
```
- ## Step 4: Launch command
+ Expect `Hello Holoscan!`, the requested 5.x version, and successful API access.
+ Run the installed `first_pipeline/python/first_pipeline.py` example when present
+ for graph execution coverage. Check the release's installed example tree and
+ README before adding module/GPU tests; a Core import alone does not qualify
+ Vision, Visualization, Inference, graphics, or camera support.
- - Read https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara-holoscan/containers/holoscan.
- - Explain the docker flags below to the user.
- - Refer the user to that link for additional flags (e.g., how to mount V4L2 video devices).
+ ## 4. Report results and reuse the image
```bash
- docker run -it --rm \
- --runtime=nvidia --gpus all --cap-add CAP_SYS_PTRACE \
- --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
- nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>
- # Examples: /opt/nvidia/holoscan/examples/
- # Mount files: -v /host/path:/container/path
- # GUI examples: add -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY
+ docker run --rm -it --gpus all "$IMAGE" bash
```
- Next:
- - Explore: `ls /opt/nvidia/holoscan/examples/`
- - Walk through one: `/holoscan-explain-example`
+ Add mounts for the user's project or devices as the application needs them.
+ For GUI workloads follow the selected release's display/graphics instructions;
+ keep initial verification independent of display and datasets.
- ## Troubleshooting
+ - GPU passthrough failure: check the host driver and Container Toolkit setup.
+ - Missing tag: report publication status and offer source; keep the 5.x target.
+ - Missing examples or Python components: inspect the pulled image tag/digest;
+ verify it is the development image for the selected release.
- - **`docker: Error response from daemon: could not select device driver "nvidia"`.** NVIDIA Container Toolkit is missing or not configured. Install per the link in Step 2 and restart Docker.
- - **CUDA init failure inside the container.** Tag suffix doesn't match the host. Re-check `nvidia-smi` CUDA Version and the table in Step 1.
- - **Segmentation fault when launching an example.** `ulimit -s 32768` wasn't applied inside the container. Use the `bash -c "ulimit -s 32768 && ..."` pattern shown in Step 3.
- - **Holoviz example hangs / no window over SSH.** YAML wasn't patched to `headless: true`. Use the `sed` injection shown in Step 3.
- - **`video_replayer` can't find data.** Set `HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data` — overrides the YAML's hard-coded path.
+ Report the image tag/digest, architecture, SDK version, tests run, and skipped
+ hardware or module checks.