holoscan-install-debian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Holoscan Debian/apt Installation

Holoscan Debian/apt 安装指南

Purpose

目的

Install the Holoscan SDK C++ runtime + headers on Ubuntu using NVIDIA's apt repo, selecting the right

holoscan-cuda-*

package for the host's CUDA driver and verifying with the bundled C++ examples.

在Ubuntu上通过NVIDIA的apt仓库安装Holoscan SDK C++运行时及头文件，为主机的CUDA驱动选择合适的

holoscan-cuda-*

包，并通过附带的C++示例进行验证。

Prerequisites

前提条件

Ubuntu x86_64 (22.04 / 24.04) or ARM64 (Jetson / IGX) with an NVIDIA GPU and working driver (
```
nvidia-smi
```
).

sudo

and network access to

developer.download.nvidia.com

and

docs.nvidia.com

```
cuda-keyring
```
package (Step 2 installs it if missing).

搭载NVIDIA GPU且驱动正常运行（可通过
```
nvidia-smi
```
验证）的Ubuntu x86_64（22.04 / 24.04）或ARM64（Jetson / IGX）系统。

拥有

sudo

权限，且能访问

developer.download.nvidia.com

和

docs.nvidia.com

网络资源。

已安装
```
cuda-keyring
```
包（若未安装，步骤2会自动安装）。

Limitations

限制说明

No Python bindings from apt — pair with
```
/holoscan-install-wheel
```
if the user needs Python.
Ubuntu-only. Other distros must use the container or wheel install.
Package variant must match the host CUDA driver (
```
holoscan-cuda-12
```
vs
```
holoscan-cuda-13
```
); wrong variant → "CUDA driver version is insufficient".

apt安装包不包含Python绑定；若用户需要Python支持，请搭配/holoscan-install-wheel使用。
仅支持Ubuntu系统。其他发行版需使用容器或wheel安装方式。
包版本必须与主机CUDA驱动匹配（
```
holoscan-cuda-12
```
vs
```
holoscan-cuda-13
```
）；版本不匹配会导致“CUDA driver version is insufficient”错误。

Step 0: Consult the Official Install Instructions

步骤0：参考官方安装说明

Fetch the Debian/apt section of

https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html

before installing. Extract:

Exact package names (

holoscan-cuda-12

holoscan-cuda-13

holoscan

)

Supported Ubuntu versions
The cuda-keyring URL for the right distro

If the doc disagrees with anything below, the doc wins.

Determine OS version and CUDA variant if not already known — run in parallel:

bash

lsb_release -a 2>/dev/null || cat /etc/os-release
nvidia-smi 2>&1 | head -5

CUDA variant rule — pick the apt package:

nvidia-smi CUDA Version	Package
13.x+	`holoscan-cuda-13`
12.x (on IGX)	`holoscan`
12.x (not on IGX)	`holoscan-cuda-12`
12.x (nvgpu)	`holoscan-cuda-12`

安装前，请查看

https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html

中的Debian/apt章节内容，提取以下信息：

准确的包名（

holoscan-cuda-12

、

holoscan-cuda-13

、

holoscan

）

支持的Ubuntu版本
对应发行版的cuda-keyring下载链接

若本文内容与官方文档冲突，以官方文档为准。

若尚未知晓系统版本和CUDA适配版本，可并行运行以下命令查询：

bash

lsb_release -a 2>/dev/null || cat /etc/os-release
nvidia-smi 2>&1 | head -5

CUDA版本适配规则——选择对应apt包：

nvidia-smi显示的CUDA版本	对应包
13.x+	`holoscan-cuda-13`
12.x（IGX平台）	`holoscan`
12.x（非IGX平台）	`holoscan-cuda-12`
12.x（nvgpu环境）	`holoscan-cuda-12`

Step 1: Prerequisites Check

步骤1：前提条件检查

bash

dpkg -l | grep cuda-keyring
dpkg -l | grep -E "holoscan-cuda-(12|13)|^ii  holoscan "
apt-cache show holoscan-cuda-13 holoscan-cuda-12 2>/dev/null | grep -E "^(Package|Version)"

Decision rules based on what Step 1 found:

Skip the keyring step if
```
cuda-keyring
```
is already installed.
Skip
```
apt-get update
```
if the repo is already configured and the package is visible in
```
apt-cache show
```
.
Skip Step 2 entirely and proceed directly to Step 3 if the correct package variant is already installed (e.g.
```
holoscan-cuda-12
```
when targeting cu12).

bash

dpkg -l | grep cuda-keyring
dpkg -l | grep -E "holoscan-cuda-(12|13)|^ii  holoscan "
apt-cache show holoscan-cuda-13 holoscan-cuda-12 2>/dev/null | grep -E "^(Package|Version)"

根据步骤1的检查结果执行对应操作：

若已安装
```
cuda-keyring
```
，跳过密钥环安装步骤。
若仓库已配置且
```
apt-cache show
```
能查询到对应包，跳过
```
apt-get update
```
步骤。
若已安装正确版本的包（例如目标为cu12时已安装
```
holoscan-cuda-12
```
），直接跳过步骤2，进入步骤3。

Step 2: Install

步骤2：安装

Skip this step if the package is already installed (detected in Step 1) or if user is on IGX platform.

bash

undefined

若步骤1检测到已安装对应包，或用户使用IGX平台，请跳过此步骤。

bash

undefined

If cuda-keyring missing (adjust ubuntu2204/ubuntu2404 as needed) and not on IGX platform:

若未安装cuda-keyring（根据系统调整ubuntu2204/ubuntu2404）且非IGX平台：

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb && sudo apt-get update

sudo apt-get install -y holoscan-cuda-12 # or holoscan-cuda-13

undefined

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb && sudo apt-get update

sudo apt-get install -y holoscan-cuda-12 # 或安装holoscan-cuda-13

undefined

Step 3: Verify

步骤3：验证

Set the env once for the rest of this step, then run the three C++ checks:

bash

HS=/opt/nvidia/holoscan
export LD_LIBRARY_PATH=$HS/lib
export HOLOSCAN_INPUT_PATH=$HS/data
ulimit -s 32768

ls $HS/examples/{hello_world,tensor_interop,video_replayer}/

先设置环境变量，再执行三项C++验证：

bash

HS=/opt/nvidia/holoscan
export LD_LIBRARY_PATH=$HS/lib
export HOLOSCAN_INPUT_PATH=$HS/data
ulimit -s 32768

ls $HS/examples/{hello_world,tensor_interop,video_replayer}/

hello_world — expected: "Hello World!"

hello_world — 预期输出: "Hello World!"

$HS/examples/hello_world/cpp/hello_world

tensor_interop — expected: tensors doubling each pass, "Graph execution finished."

tensor_interop — 预期输出: 张量每次传递后翻倍，最终显示"Graph execution finished."

If "CUDA driver version is insufficient": swap package variant:

若出现"CUDA driver version is insufficient"错误：更换包版本:

sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12

$HS/examples/tensor_interop/cpp/tensor_interop

video_replayer (10 frames, headless) — expected: Vulkan selects NVIDIA GPU, "Graph execution finished."

video_replayer（无界面模式，播放10帧）— 预期输出: Vulkan选择NVIDIA GPU，最终显示"Graph execution finished."

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

始终使用无界面模式：无论有无显示器均可运行，避免SSH连接下的GUI故障。

ls $HS/data/racerx 2>/dev/null || sudo $HS/examples/download_example_data python3 -c " c=open('$HS/examples/video_replayer/cpp/video_replayer.yaml').read() c=c.replace('count: 0','count: 10').replace('repeat: true','repeat: false').replace('realtime: true','realtime: false') c=c.replace(' width: 854',' headless: true\n width: 854') open('/tmp/vr.yaml','w').write(c)" $HS/examples/video_replayer/cpp/video_replayer --config /tmp/vr.yaml

undefined

undefined

Step 4: Give the User the Reusable Env Snippet

步骤4：提供可复用的环境变量代码片段

Once verified, share this snippet with user and suggest adding it to their shell startup file (e.g.,

~/.bashrc

) if they want it to persist across sessions:

bash

export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib:${LD_LIBRARY_PATH}
export HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data
ulimit -s 32768

Then offer next steps:

Add Python support:
```
/holoscan-install-wheel
```
Explore examples:
```
ls /opt/nvidia/holoscan/examples/
```
Walk through a specific example:
```
/explain-example
```
Start building a custom Holoscan application

验证通过后，可将以下代码片段分享给用户，建议添加到shell启动文件（如

~/.bashrc

）中，以便在所有会话中生效：

bash

export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib:${LD_LIBRARY_PATH}
export HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data
ulimit -s 32768

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

添加Python支持：执行/holoscan-install-wheel
探索示例：运行
```
ls /opt/nvidia/holoscan/examples/
```
查看特定示例讲解：执行/explain-example
开始构建自定义Holoscan应用

Troubleshooting

故障排查

python3 -c "import holoscan"
fails after apt install. Expected — the Debian package has been C++ only since v3.0.0. Run
```
/holoscan-install-wheel
```
to add Python bindings.
"CUDA driver version is insufficient" when running an example. Wrong package variant. Re-check
```
nvidia-smi
```
CUDA Version and swap variants:
```
sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12
```
(or vice versa).
E: Unable to locate package holoscan-cuda-12
.
```
cuda-keyring
```
not installed or repo not yet pulled. Run the keyring +
```
apt-get update
```
block in Step 2 (adjust
```
ubuntu2204
```
/
```
ubuntu2404
```
to match the host).
Segmentation fault when launching an example.
```
ulimit -s 32768
```
not set in the current shell. Prepend it to the command (Step 3 pattern).

error while loading shared libraries: libholoscan_core.so
.

LD_LIBRARY_PATH

is unset. Use the env snippet from Step 4 —

export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib

video_replayer
can't find data. Set

HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data

, or run

sudo /opt/nvidia/holoscan/examples/download_example_data

to fetch the

racerx

dataset.

python3 -c "import holoscan"
在apt安装后执行失败。此为正常现象——自v3.0.0版本起，Debian包仅包含C++组件。如需Python绑定，请执行/holoscan-install-wheel。
运行示例时出现"CUDA driver version is insufficient"错误。 包版本不匹配。重新检查
```
nvidia-smi
```
显示的CUDA版本，更换对应包：
```
sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12
```
（反之亦然）。
出现
E: Unable to locate package holoscan-cuda-12
错误。未安装cuda-keyring或未拉取仓库资源。执行步骤2中的密钥环安装+
```
apt-get update
```
代码块（根据主机系统调整
```
ubuntu2204
```
/
```
ubuntu2404
```
）。
启动示例时出现Segmentation fault错误。 当前shell未设置
```
ulimit -s 32768
```
。可在命令前添加该配置（参考步骤3的格式）。

出现
error while loading shared libraries: libholoscan_core.so
错误。未设置

LD_LIBRARY_PATH

。使用步骤4中的环境变量代码片段——执行

export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib

。

video_replayer
无法找到数据。设置

HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data

，或执行

sudo /opt/nvidia/holoscan/examples/download_example_data

下载

racerx

数据集。