---name: holoscan-install-containerversion: 1.0.0description: Install Holoscan SDK via the NGC Docker container. Use for container-based installs; not for native apt/pip/Conda installs.license: Apache-2.0metadata: author: Holoscan Team <holoscan-team@nvidia.com>github-url: https://github.com/nvidia-holoscan/holoscan-sdktags: ---

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

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

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.

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

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

Next:

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