v1.0.0 to v2.0.0

74 added, 104 removed. Audit A to A.

---

name: holoscan-install-debian

- version: "1.0.0"

- description: "Install Holoscan SDK natively on Ubuntu via apt. Use for C++ installs on Ubuntu; pair with /holoscan-install-wheel for Python."

+ description: "Install Holoscan SDK 5.x native C++ Debian packages on Ubuntu 24.04, choosing the full SDK or matching modular packages."

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

- debian

- - apt

- - ubuntu

---

- # Holoscan Debian/apt Installation

- ## Purpose

- Install the Holoscan SDK C++ runtime + headers on Ubuntu using NVIDIA's apt repo, selecting the right `holoscan-cuda-*` package for the host's CUDA driver and verifying with the bundled C++ examples.

- ## Prerequisites

- - Ubuntu x86_64 (22.04 / 24.04) or ARM64 (Jetson / IGX) with an NVIDIA GPU and working driver (`nvidia-smi`).

- - `sudo` and network access to `developer.download.nvidia.com` and `docs.nvidia.com`.

- - `cuda-keyring` package (Step 2 installs it if missing).

- ## Limitations

- - No Python bindings from apt — pair with `/holoscan-install-wheel` if the user needs Python.

- - Ubuntu-only. Other distros must use the container or wheel install.

- - Package variant must match the host CUDA driver (`holoscan-cuda-12` vs `holoscan-cuda-13`); wrong variant → "CUDA driver version is insufficient".

- ## Step 0: Consult the Official Install Instructions

+ # Holoscan 5.x Debian Installation

- Fetch the Debian/apt section of `https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html` before installing. Extract:

+ ## Release and platform checks

- - Exact package names (`holoscan-cuda-12`, `holoscan-cuda-13`, `holoscan`)

- - Supported Ubuntu versions

- - The cuda-keyring URL for the right distro

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

- If the doc disagrees with anything below, the doc wins.

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

- Determine OS version and CUDA variant if not already known — run in parallel:

+ ## Select packages and inspect availability

- ```bash

- lsb_release -a 2>/dev/null || cat /etc/os-release

- nvidia-smi 2>&1 | head -5

- ```

+ This path supplies **C++** libraries, headers, CMake configuration, and C++

+ examples under `/usr`. Python bindings use `holoscan-install-wheel` separately.

+ Support in the planned artifact set is Ubuntu 24.04 x86_64 and SBSA arm64;

+ SBSA does not imply Tegra/iGPU support.

- **CUDA variant rule — pick the apt package:**

+ | Goal | Package |

+ | --- | --- |

+ | Full SDK | `holoscan` |

+ | Core libraries only | `holoscan-core` |

+ | Optional modules | `holoscan-vision`, `holoscan-visualization`, `holoscan-inference` |

- | nvidia-smi CUDA Version | Package |

- |------------------------|---------|

- | 13.x+ | `holoscan-cuda-13` |

- | 12.x (on IGX) | `holoscan` |

- | 12.x (not on IGX) | `holoscan-cuda-12` |

- | 12.x (nvgpu) | `holoscan-cuda-12` |

+ Inspect `/etc/os-release`, `uname -m`, `nvidia-smi`, and existing packages.

+ Use the release-specific network/local installer from

+ [Holoscan Downloads](https://developer.nvidia.com/holoscan-downloads) to configure

+ the CUDA APT repository when needed. Choose `ubuntu2404/x86_64` or

+ `ubuntu2404/sbsa` as appropriate; use the published release-specific installer

+ instructions and package names.

- ## Step 1: Prerequisites Check

+ After repository setup is authorized, refresh metadata and inspect candidates:

```bash

- dpkg -l | grep cuda-keyring

- dpkg -l | grep -E "holoscan-cuda-(12|13)|^ii holoscan "

- apt-cache show holoscan-cuda-13 holoscan-cuda-12 2>/dev/null | grep -E "^(Package|Version)"

+ sudo apt update

+ apt-cache policy holoscan holoscan-core holoscan-vision holoscan-visualization holoscan-inference

+ apt-cache madison holoscan holoscan-core

```

- Decision rules based on what Step 1 found:

- - Skip the keyring step if `cuda-keyring` is already installed.

- - Skip `apt-get update` if the repo is already configured and the package is visible in `apt-cache show`.

- - **Skip Step 2 entirely** and proceed directly to Step 3 if the correct package variant is already installed (e.g. `holoscan-cuda-12` when targeting cu12).

- ## Step 2: Install

- Skip this step if the package is already installed (detected in Step 1) or if user is on IGX platform.

+ Choose the exact APT version corresponding to the requested 5.x release.

+ A candidate from 4.x is not an available 5.x package. Keep every optional

+ module on the same Core release. Preview dependency changes before installing:

```bash

- # If cuda-keyring missing (adjust ubuntu2204/ubuntu2404 as needed) and not on IGX platform:

- wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb

- sudo dpkg -i cuda-keyring_1.1-1_all.deb && sudo apt-get update

- sudo apt-get install -y holoscan-cuda-12 # or holoscan-cuda-13

+ # APT_VERSION is the exact available 5.x Debian version, including its revision.

+ apt-get --simulate install "holoscan=${APT_VERSION}"

```

- ## Step 3: Verify

+ For Core-only, substitute `holoscan-core`. Add selected optional module packages

+ with their matching versions. Review the simulated transaction for removals or

+ an existing 4.x installation before applying it.

+ If simulation fails or proposes changes outside the requested scope, stop and

+ report the failing command/output or conflicting changes. Resolve the conflict

+ or obtain authorization for the expanded scope before installing. An existing

+ 4.x installation alone does not block an upgrade the user requested.

- Set the env once for the rest of this step, then run the three C++ checks:

+ After the simulated transaction is acceptable, install the selected package set:

```bash

- HS=/opt/nvidia/holoscan

- export LD_LIBRARY_PATH=$HS/lib

- export HOLOSCAN_INPUT_PATH=$HS/data

- ulimit -s 32768

- ls $HS/examples/{hello_world,tensor_interop,video_replayer}/

- # hello_world — expected: "Hello World!"

- $HS/examples/hello_world/cpp/hello_world

- # tensor_interop — expected: tensors doubling each pass, "Graph execution finished."

- # If "CUDA driver version is insufficient": swap package variant:

- # sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12

- $HS/examples/tensor_interop/cpp/tensor_interop

- # video_replayer (10 frames, headless) — expected: Vulkan selects NVIDIA GPU, "Graph execution finished."

- # Always run headless: works with or without a display, avoids GUI failure modes over SSH.

- ls $HS/data/racerx 2>/dev/null || sudo $HS/examples/download_example_data

- python3 -c "

- c=open('$HS/examples/video_replayer/cpp/video_replayer.yaml').read()

- c=c.replace('count: 0','count: 10').replace('repeat: true','repeat: false').replace('realtime: true','realtime: false')

- c=c.replace(' width: 854',' headless: true\n width: 854')

- open('/tmp/vr.yaml','w').write(c)"

- $HS/examples/video_replayer/cpp/video_replayer --config /tmp/vr.yaml

+ sudo apt install "holoscan=${APT_VERSION}"

```

- ## Step 4: Give the User the Reusable Env Snippet

- Once verified, share this snippet with user and suggest adding it to their shell startup file (e.g., `~/.bashrc`) if they want it to persist across sessions:

+ ## Verify C++ support

```bash

- export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib:${LD_LIBRARY_PATH}

- export HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data

- ulimit -s 32768

+ dpkg-query -W 'holoscan*'

+ dpkg -L holoscan-core-cuda-13

```

- Then offer next steps:

- - Add Python support: `/holoscan-install-wheel`

- - Explore examples: `ls /opt/nvidia/holoscan/examples/`

- - Walk through a specific example: `/explain-example`

- - Start building a custom Holoscan application

- ## Troubleshooting

+ The unsuffixed component packages select CUDA 13 native packages, such as

+ `holoscan-core-cuda-13`; inspect their installed versions and file lists.

+ Use the package file list to locate the installed `hello_world/cpp/hello_world`

+ and `hello_core/cpp/hello_core` executables under the system library hierarchy.

+ Run them and expect `Hello Holoscan!` and `holoscan core sample complete`.

+ Use the installed `hello_world` source and its `CMakeLists.txt` for a small

+ consumer build in a user-writable build directory; verify `find_package(holoscan)`

+ and the `holoscan::core` target. Check that `cmake --version` reports 4.0 or

+ newer first; Ubuntu 24.04's default CMake 3.28 cannot configure the consumer.

+ Inspect package contents rather than exporting the old `/opt/nvidia/holoscan/lib`

+ path. Record missing example packages as a verification gap.

- - **`python3 -c "import holoscan"` fails after apt install.** Expected — the Debian package has been C++ only since v3.0.0. Run `/holoscan-install-wheel` to add Python bindings.

- - **"CUDA driver version is insufficient" when running an example.** Wrong package variant. Re-check `nvidia-smi` CUDA Version and swap variants: `sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12` (or vice versa).

- - **`E: Unable to locate package holoscan-cuda-12`.** `cuda-keyring` not installed or repo not yet pulled. Run the keyring + `apt-get update` block in Step 2 (adjust `ubuntu2204`/`ubuntu2404` to match the host).

- - **Segmentation fault when launching an example.** `ulimit -s 32768` not set in the current shell. Prepend it to the command (Step 3 pattern).

- - **`error while loading shared libraries: libholoscan_core.so`.** `LD_LIBRARY_PATH` is unset. Use the env snippet from Step 4 — `export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib`.

- - **`video_replayer` can't find data.** Set `HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data`, or run `sudo /opt/nvidia/holoscan/examples/download_example_data` to fetch the `racerx` dataset.

+ Core declares CUDA development dependencies; Vision supplies its CV-CUDA

+ runtime, and Inference recommends TensorRT 10 runtime libraries. Check the

+ application's selected modules and dependencies before claiming full support.

+ Report installed package versions, C++ checks, and any untested GPU/module paths.

+ If Python import is requested, explain the C++/Python package split and use the

+ wheel workflow with the same SDK release.