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

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.

Step 1: Pick the tag

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

`nvidia-smi` CUDA Version	Suffix
13.x+	`cuda13`
12.x, Ampere/Ada dGPU	`cuda12-dgpu`
12.x, ARM64 iGPU (nvgpu)	`cuda12-igpu`

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.

Step 2: Verify GPU passthrough, then pull

bash

docker run --rm --gpus all ubuntu:22.04 nvidia-smi 2>&1 | tail -5

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

bash

docker pull nvcr.io/nvidia/clara-holoscan/holoscan:<TAG>

Step 3: Verify with six examples

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.

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
"

Step 4: Launch command

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

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

Explore:
```
ls /opt/nvidia/holoscan/examples/
```
Walk through one:
```
/holoscan-explain-example
```

Troubleshooting

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.

holoscan-install-container

NPX Install

Tags

SKILL.md Content

Holoscan NGC Container Installation

Purpose

Prerequisites

Limitations

Instructions

Step 1: Pick the tag

Step 2: Verify GPU passthrough, then pull

Step 3: Verify with six examples

Step 4: Launch command

Troubleshooting