holoscan-install-wheel

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:

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:

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

If missing:

python3 -m venv ~/holoscan/venv

Then activate:

Step 2: Install

Step 3: Verify

The venv must be active for all commands below.

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.

Step 4: Remind the User

They must activate the venv in each new shell session:

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

Troubleshooting

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