v1.0.0 to v2.0.0

72 added, 107 removed. Audit A to A.

---

name: holoscan-install-wheel

- version: "1.0.0"

- description: "Install Holoscan SDK Python wheel via pip into a venv. Use for Python installs; not for native C++/apt or Conda installs."

+ description: "Install Holoscan SDK 5.x CUDA 13 Python wheels in an isolated environment, choosing the full stack or version-matched components."

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

- - pip

+ - installation

- wheel

- - python

---

- # Holoscan pip Wheel Installation

- ## Purpose

- Install the Holoscan SDK Python bindings via the `holoscan-cu12` / `holoscan-cu13` pip wheel into a virtual environment, and verify with `hello_world` and `video_replayer`.

- ## Prerequisites

- - Linux x86_64 with NVIDIA GPU + driver (`nvidia-smi`).

- - CUDA Toolkit on `PATH` matching the host CUDA major (12 or 13).

- - Python 3.10–3.13 with `venv` available.

- - Network access to PyPI and `docs.nvidia.com`.

- ## Limitations

- - Python only. For C++ headers/libs, pair with `/holoscan-install-debian`.

- - `holoscan-cu12` and `holoscan-cu13` are mutually exclusive — wheel must match host CUDA driver.

- - `video_replayer` data ships only with the Debian package; without it, set `HOLOSCAN_INPUT_PATH` to a directory containing `racerx/`.

- - `ulimit -s 32768` is recommended in every shell that runs Holoscan — without it some apps emit a stack-size warning or, in rarer cases, segfault.

- ## Step 0: Consult the Official Install Instructions

- Always fetch the pip-wheel section of `https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html` before installing. Extract: exact wheel package names (`holoscan-cu12`, `holoscan-cu13`), the supported Python range for the current release, prerequisites that must be on `PATH` (CUDA Toolkit), and any optional extras (LibTorch / ONNX Runtime version pins). If the doc disagrees with anything below, the doc wins.

- You need the CUDA variant already determined. If not known, run `nvidia-smi 2>&1 | head -5` first.

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

- | nvidia-smi CUDA Version | pip package |

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

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

- | 12.x (any GPU) | `holoscan-cu12` |

- Prerequisites: CUDA Toolkit on PATH, Python 3.10–3.13. Optional extras: LibTorch 2.11.0+, ONNX Runtime 1.22.0+.

- Always install into a Python virtual environment — this avoids system-package conflicts and is required on Ubuntu 24.04 (which blocks system-wide pip entirely).

- ## Step 1: Create and Activate the venv

- Check if one exists first:

- ```bash

- ls ~/holoscan/venv 2>/dev/null && echo "exists" || echo "missing"

- ```

- If missing:

- ```bash

- python3 -m venv ~/holoscan/venv

- ```

- Then activate:

- ```bash

- source ~/holoscan/venv/bin/activate

- ```

+ # Holoscan 5.x Python Wheel Installation

- ## Step 2: Install

+ ## Release and platform checks

- ```bash

- pip install holoscan-cu12 # or holoscan-cu13

- ```

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

- ## Step 3: Verify

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

- The venv must be active for all commands below.

+ ## Choose a distribution

- ```bash

- # Basic import — expected: version string, e.g. "4.1.0"

- # The stack-size RuntimeWarning is harmless; ulimit -s 32768 suppresses it.

- python3 -c "import holoscan; print(holoscan.__version__)"

+ Wheels contain Python bindings, typing information, and native runtime libraries.

+ C++ headers, CMake files, examples, and sample data are separate. For native

+ C++ development use Debian packages or a source build.

- # Fetch Python examples from GitHub at the installed version tag.

- # These are official NVIDIA examples, fetched over HTTPS and pinned to the tag

- # matching the installed wheel (v${SDK_VER}). Before running them, tell the user

- # you're about to download and execute remote example scripts from this URL. If

- # they decline or GitHub is unreachable, skip to browsing the examples in Step 4.

- SDK_VER=$(python3 -c "import holoscan; print(holoscan.__version__)")

- BASE="https://raw.githubusercontent.com/nvidia-holoscan/holoscan-sdk/v${SDK_VER}/examples"

+ | Goal | Distribution |

+ | --- | --- |

+ | Full stack | `holoscan` (selects `holoscan-cu13`) |

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

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

- # hello_world — expected: "Hello World!"

- curl -fsSL "${BASE}/hello_world/python/hello_world.py" -o /tmp/hs_hello_world.py

- ulimit -s 32768 && python3 /tmp/hs_hello_world.py

+ Inspect the host, `python3 --version`, and `getconf GNU_LIBC_VERSION`. Confirm

+ regular CPython 3.12–3.14, glibc 2.39 or newer, a compatible Linux architecture,

+ and the CUDA 13 driver/runtime prerequisites. An active Conda environment does

+ not imply a supported Conda package. Prefer a separate venv for this workflow.

+ If these prerequisites are unmet, report the failed check and stop before

+ installation. Compare the driver version against the selected release's

+ documented CUDA 13 driver requirement; a toolkit version alone is insufficient.

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

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

- curl -fsSL "${BASE}/video_replayer/python/video_replayer.py" -o /tmp/hs_video_replayer.py

- curl -fsSL "${BASE}/video_replayer/python/video_replayer.yaml" -o /tmp/hs_video_replayer.yaml

- python3 -c "

- c = open('/tmp/hs_video_replayer.yaml').read()

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

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

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

- ulimit -s 32768 && HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data \

- python3 /tmp/hs_video_replayer.py --config /tmp/hs_video_replayer_run.yaml

- ```

+ Confirm the exact published 5.x distribution version on PyPI or the selected

+ release's documented index; reserved package names are not installable SDKs.

+ If absent, offer source instead of resolving an unpinned package to 4.x.

+ Keep all components on the same SDK version.

- Note: `video_replayer` needs the racerx data files. These ship with the Debian package at `/opt/nvidia/holoscan/data`. If the Debian package is not installed, run `sudo /opt/nvidia/holoscan/examples/download_example_data` first (requires the apt package to be installed for that script), or set `HOLOSCAN_INPUT_PATH` to wherever the data lives.

+ ## Install and verify

- ## Step 4: Remind the User

+ If an installation or verification command fails, stop and report the failing

+ command and output. Do not continue to the example or report success after a

+ failed prerequisite, package-index, dry-run, install, dependency, or import check.

- They must activate the venv in each new shell session:

+ Choose a fresh venv path, or reuse an environment the user selected after

+ checking its contents. Explain the chosen packages before installing:

```bash

- source ~/holoscan/venv/bin/activate

- ulimit -s 32768 # suppress stack-size warning

+ python3 -m venv ~/holoscan/venv-5x

+ source ~/holoscan/venv-5x/bin/activate

+ # SDK_VERSION is the exact published Python distribution version for 5.x.

+ python -m pip index versions holoscan

+ python -m pip install --dry-run "holoscan==${SDK_VERSION}"

+ python -m pip install "holoscan==${SDK_VERSION}"

+ python -m pip check

+ python -m pip list --format=freeze

+ python -c 'import holoscan as hs; print(hs.__version__); print(hs.RealtimeClock); print(len(hs.registry.operators()))'

```

- Then offer next steps:

- - Explore Python examples at `https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples`

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

- - Start building a custom Holoscan application

+ For Core-only use `holoscan-core-cu13` in the index, dry-run, and install

+ commands. Add optional component wheels at the exact matching SDK version.

+ Vision resolves CV-CUDA and NPP Python dependencies. The host supplies the

+ driver and CUDA 13 runtime; Inference expects TensorRT 10 in the application

+ environment. Verify optional providers separately when selected:

+ `holoscan_vision`, `holoscan_visualization`, and `holoscan_inference`.

- ## Troubleshooting

+ For execution coverage, obtain `examples/first_pipeline/python/first_pipeline.py`

+ from the source ref corresponding to this release. Inspect it before execution

+ and run it in the venv; it is bounded and needs no RacerX data or display.

+ Prefer an existing matching checkout. Do not construct a Git tag from a Python

+ version string: Early Access packaging versions and source refs can differ.

+ The 4.x `hello_world.py`, `tensor_interop`, and `video_replayer` smoke sequence

+ does not describe the 5.x Python examples.

- - **`pip install holoscan-cu12` errors with "externally-managed-environment".** Ubuntu 24.04 blocks system-wide pip. Create and activate the venv from Step 1 first.

- - **`ImportError` / wrong CUDA at `import holoscan`.** Wheel variant doesn't match host CUDA. Uninstall and reinstall the matching one: `pip uninstall -y holoscan-cu13 && pip install holoscan-cu12` (or vice versa).

- - **`RuntimeWarning: stack size ...`.** Harmless, but set `ulimit -s 32768` in the current shell to silence it.

- - **Segmentation fault when running an example.** `ulimit -s 32768` wasn't set. Set it before `python3 ...`.

- - **`video_replayer` can't find `racerx/`.** `HOLOSCAN_INPUT_PATH` isn't pointing at a directory containing it. Install the Debian package for `/opt/nvidia/holoscan/data`, or set `HOLOSCAN_INPUT_PATH` to wherever the data lives.

- - **`source: no such file: ~/holoscan/venv/bin/activate` in a new shell.** Venv wasn't created or path differs. Re-run Step 1 or correct the path.

+ Report the Python, SDK, and component versions; import, dependency, and graph

+ checks; and any skipped module tests. An import check alone is not full runtime

+ qualification. Missing runtime libraries should be traced to the selected

+ component's prerequisites before changing unrelated system paths.