⚡

HoloscanSDKPythonwheel安装Skill holoscan-install-wheel

该技能详细说明如何通过 pip 在虚拟环境中安装 Holoscan SDK 的 Python wheel（holoscan-cu12 或 holoscan-cu13），包括环境前提条件检查、venv 创建与激活、安装、以及使用 hello_world 和 video_replayer 示例进行验证，同时涵盖常见故障排查和注意事项。关键词：Holoscan SDK, pip, wheel, CUDA, 虚拟环境, Python, 安装, NVIDIA, Holoscan 安装。

物理AI基础设施 0 次安装 0 次浏览 更新于 9/7/2026
名称 holoscan-install-wheel
版本 “1.0.0”
描述 “通过 pip 将 Holoscan SDK Python wheel 安装到 venv 中。用于 Python 安装；不用于原生 C++/apt 或 Conda 安装。”
开源协议 Apache-2.0 metadata:
作者 “Holoscan Team holoscan-team@nvidia.com” github-url: “https://github.com/nvidia-holoscan/holoscan-sdk” tags: - holoscan - 安装 - pip - wheel - python

Holoscan pip Wheel 安装

目的

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

前提条件

  • Linux x86_64，带 NVIDIA GPU 和驱动（nvidia-smi）。
  • 在 PATH 中的 CUDA Toolkit 与主机 CUDA 主版本匹配（12 或 13）。
  • 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 版本 pip 包
13.x+ holoscan-cu13
12.x（任意 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   # 或 holoscan-cu13

步骤 3：验证

以下所有命令必须在 venv 激活状态下执行。

# 基本导入——预期：版本字符串，例如 "4.1.0"
# 堆栈大小 RuntimeWarning 无害；ulimit -s 32768 可抑制它。
python3 -c "import holoscan; print(holoscan.__version__)"

# 从 GitHub 获取安装版本标签对应的 Python 示例。
# 这些是 NVIDIA 官方示例，通过 HTTPS 获取并锁定到与已安装 wheel 匹配的标签（v${SDK_VER}）。
# 在运行它们之前，告诉用户你将从此 URL 下载并执行远程示例脚本。如果用户拒绝或 GitHub 不可达，
# 则跳到步骤 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——预期："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 帧，无头）——预期："Graph execution finished."
# 始终以无头模式运行：无论有无显示器均可运行，避免 SSH 上的 GUI 故障模式。
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:
  width: 854','holoviz:
  headless: true
  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   # 抑制堆栈大小警告

然后提供后续步骤：

  • 浏览 Python 示例：https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples
  • 深入了解某个示例：/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 未指向包含 racerx/ 的目录。安装 Debian 包以获得 /opt/nvidia/holoscan/data，或将 HOLOSCAN_INPUT_PATH 设置为数据所在位置。
  • 在新 shell 中 source: no such file: ~/holoscan/venv/bin/activate。 说明 venv 未创建或路径不同。请重新执行步骤 1 或修正路径。