holoscan-install-wheel

Holoscan pip Wheel 安装

用途

通过 holoscan-cu12 / holoscan-cu13 pip wheel，在虚拟环境中安装 Holoscan SDK Python 绑定，并使用 hello_world 和 video_replayer 进行验证。

先决条件

• Linux x86_64，配备 NVIDIA GPU 和驱动（nvidia-smi）。
• PATH 中有与主机 CUDA 主版本（12 或 13）匹配的 CUDA Toolkit。
• Python 3.10–3.13，并可使用 venv。
• 可访问 PyPI 和 docs.nvidia.com。

限制

• 仅支持 Python。若要使用 C++ 头文件/库，请搭配 /holoscan-install-debian。
• holoscan-cu12 和 holoscan-cu13 互斥，wheel 必须与主机 CUDA 驱动匹配。
• video_replayer 数据仅随 Debian 软件包提供；若未安装，请将 HOLOSCAN_INPUT_PATH 设为包含 racerx/ 的目录。
• 建议在每个运行 Holoscan 的 shell 中执行 ulimit -s 32768。否则，部分应用会发出栈大小警告，极少数情况下还会发生段错误。

第 0 步：查阅官方安装说明

安装前，务必先获取 https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html 中的 pip wheel 部分。提取以下信息：准确的 wheel 软件包名称（holoscan-cu12、holoscan-cu13）、当前版本支持的 Python 范围、必须位于 PATH 中的先决条件（CUDA Toolkit），以及任何可选扩展（LibTorch / ONNX Runtime 版本要求）。如果文档与以下内容有出入，以文档为准。

需要先确定 CUDA 变体。如果尚不确定，请先运行 nvidia-smi 2>&1 | head -5。

CUDA 变体规则——选择 pip 软件包：

nvidia-smi CUDA Version	pip 软件包
13.x+	holoscan-cu13
12.x (any GPU)	holoscan-cu12

先决条件：PATH 中有 CUDA Toolkit，Python 3.10–3.13。可选扩展：LibTorch 2.11.0+、ONNX Runtime 1.22.0+。

务必安装到 Python 虚拟环境中，以避免系统软件包冲突；在 Ubuntu 24.04 上也必须这样做（该系统会完全阻止系统级 pip 安装）。

第 1 步：创建并激活 venv

先检查是否已存在：

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

如果不存在：

python3 -m venv ~/holoscan/venv

然后激活：

source ~/holoscan/venv/bin/activate

第 2 步：安装

pip install holoscan-cu12   # or holoscan-cu13

第 3 步：验证

以下所有命令都必须在 venv 已激活的情况下运行。

# 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

注意：video_replayer 需要 racerx 数据文件。这些文件随 Debian 软件包提供，位于 /opt/nvidia/holoscan/data。如果未安装 Debian 软件包，请先运行 sudo /opt/nvidia/holoscan/examples/download_example_data（该脚本需要先安装 apt 软件包），或将 HOLOSCAN_INPUT_PATH 设为数据所在的位置。

第 4 步：提醒用户

用户必须在每个新的 shell 会话中激活 venv：

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

然后提供后续步骤：

• 浏览 https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples 中的 Python 示例
• 演示具体示例：/explain-example
• 开始构建自定义 Holoscan 应用

故障排除

• pip install holoscan-cu12 报错，提示 "externally-managed-environment"。 Ubuntu 24.04 会阻止系统级 pip 安装。请先按照第 1 步创建并激活 venv。
• import holoscan 时出现 ImportError / CUDA 不匹配。 Wheel 变体与主机 CUDA 不匹配。请卸载并重新安装匹配的变体：pip uninstall -y holoscan-cu13 && pip install holoscan-cu12（或反过来）。
• 出现 RuntimeWarning: stack size ...。 这不会造成影响，但可在当前 shell 中设置 ulimit -s 32768 来消除此警告。
• 运行示例时发生段错误。 未设置 ulimit -s 32768。请在运行 python3 ... 前设置。
• video_replayer 找不到 racerx/。 HOLOSCAN_INPUT_PATH 未指向包含该目录的位置。请安装 Debian 软件包以获取 /opt/nvidia/holoscan/data，或将 HOLOSCAN_INPUT_PATH 设为数据所在的位置。
• 在新 shell 中出现 source: no such file: ~/holoscan/venv/bin/activate。 Venv 尚未创建，或路径不同。请重新执行第 1 步，或修正路径。