holoscan-install-wheel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Holoscan pip Wheel Installation

Holoscan pip Wheel 安装

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

通过

holoscan-cu12

holoscan-cu13

pip wheel将Holoscan SDK Python绑定安装到虚拟环境中，并使用

hello_world

和

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

搭载NVIDIA GPU及驱动（可通过
```
nvidia-smi
```
查看）的Linux x86_64系统。
系统
```
PATH
```
中配置有与主机CUDA主版本（12或13）匹配的CUDA Toolkit。
已安装Python 3.10–3.13且支持
```
venv
```
功能。
可访问PyPI和
```
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.

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

Step 0: Consult the Official Install Instructions

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

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

安装前请务必查看

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安装）。

Step 1: Create and Activate the venv

步骤1：创建并激活虚拟环境

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

先检查虚拟环境是否已存在：

bash

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

若不存在：

bash

python3 -m venv ~/holoscan/venv

然后激活：

bash

source ~/holoscan/venv/bin/activate

Step 2: Install

步骤2：安装Holoscan

bash

pip install holoscan-cu12   # or holoscan-cu13

bash

pip install holoscan-cu12   # 或 holoscan-cu13

Step 3: Verify

步骤3：验证安装

The venv must be active for all commands below.

bash

undefined

以下所有命令均需在虚拟环境激活状态下执行。

bash

undefined

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

基础导入测试——预期输出：版本字符串，例如 "4.1.0"

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

栈大小RuntimeWarning无危害；执行ulimit -s 32768可消除该警告。

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

Fetch Python examples from GitHub at the installed version tag.

从GitHub获取与已安装版本标签匹配的Python示例。

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

这些是NVIDIA官方示例，通过HTTPS获取并固定到与已安装wheel匹配的标签（v${SDK_VER}）。

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

运行前请告知用户您即将从此URL下载并执行远程示例脚本。若用户拒绝或无法访问GitHub，可跳至步骤4浏览示例。

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

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 frames, headless) — expected: "Graph execution finished."

video_replayer测试（10帧，无头模式）——预期输出："Graph execution finished."

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

始终以无头模式运行：无论有无显示器均可正常工作，避免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:\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.


注意：`video_replayer`需要racerx数据文件。这些文件随Debian包提供，路径为`/opt/nvidia/holoscan/data`。若未安装Debian包，请先运行`sudo /opt/nvidia/holoscan/examples/download_example_data`（需要已安装apt包才能使用该脚本），或将`HOLOSCAN_INPUT_PATH`设置为数据所在的目录。

Step 4: Remind the User

步骤4：提醒用户注意事项

They must activate the venv in each new shell session:

bash

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

用户在每个新的shell会话中都必须激活虚拟环境：

bash

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # 消除栈大小警告

然后可提供后续操作建议：

浏览Python示例：

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

查看具体示例讲解：
```
/explain-example
```
开始构建自定义Holoscan应用

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.

执行
pip install holoscan-cu12
时出现"externally-managed-environment"错误。 Ubuntu 24.04禁止全局pip安装，请先完成步骤1创建并激活虚拟环境。
导入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
错误。虚拟环境未创建或路径错误，请重新执行步骤1或修正路径。