Holoscan Python installation

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:

source ~/holoscan/venv/bin/activate

Step 2: Install

pip install holoscan-cu12   # or holoscan-cu13

Step 3: Verify

The venv must be active for all commands below.

# 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__)"

# 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"

# 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

# 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

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:

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # suppress stack-size warning

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.