
名称	holoscan-install-debian
版本	“1.0.0”
描述	“通过 apt 在 Ubuntu 上原生安装 Holoscan SDK。用于 Ubuntu 上的 C++ 安装；如需 Python，可搭配 /holoscan-install-wheel。”
开源协议	Apache-2.0 metadata:
作者	“Holoscan Team holoscan-team@nvidia.com” github-url: “https://github.com/nvidia-holoscan/holoscan-sdk” tags: - holoscan - install - debian - apt - ubuntu

Holoscan Debian/apt 安装

目的

使用 NVIDIA 的 apt 仓库在 Ubuntu 上安装 Holoscan SDK C++ 运行时和头文件，为主机 CUDA 驱动选择正确的 holoscan-cuda-* 软件包，并使用随附的 C++ 示例进行验证。

先决条件

Ubuntu x86_64（22.04 / 24.04）或 ARM64（Jetson / IGX），配备 NVIDIA GPU 和可用的驱动程序（nvidia-smi）。
sudo 和能够访问 developer.download.nvidia.com 和 docs.nvidia.com 的网络。
cuda-keyring 软件包（如果缺少，步骤 2 会安装）。

限制

apt 不含 Python 绑定 — 如果用户需要 Python，请配合 /holoscan-install-wheel。
仅支持 Ubuntu。其他发行版必须使用容器或 wheel 安装。
软件包变体必须与主机 CUDA 驱动匹配（holoscan-cuda-12 vs holoscan-cuda-13）；变体不对 → 出现 “CUDA driver version is insufficient”。

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

在安装之前，先获取 https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html 的 Debian/apt 部分。提取：

确切的软件包名称（holoscan-cuda-12、holoscan-cuda-13、holoscan）
受支持的 Ubuntu 版本
适用于相应发行版的 cuda-keyring URL

如果文档与以下任何内容不一致，以文档为准。

如果操作系统版本和 CUDA 变体还不知道，请确定 — 并行运行：

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`

步骤 1：先决条件检查

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 已安装，则跳过 keyring 步骤。
如果仓库已配置且软件包在 apt-cache show 中可见，则跳过 apt-get update。
如果正确的软件包变体已安装（例如针对 cu12 的 holoscan-cuda-12），则完全跳过步骤 2，直接进入步骤 3。

步骤 2：安装

如果软件包已安装（步骤 1 中检测到）或用户使用 IGX 平台，则跳过此步骤。

# 如果缺少 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   # 或 holoscan-cuda-13

步骤 3：验证

为此步骤的其余部分设置一次环境，然后运行三个 C++ 检查：

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 — 预期输出：“Hello World!”
$HS/examples/hello_world/cpp/hello_world

# tensor_interop — 预期输出：张量每一遍翻倍，“Graph execution finished.”
# 如果出现 “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 帧，无头）— 预期输出：Vulkan 选择 NVIDIA GPU，“Graph execution finished.”
# 始终无头运行：无论有无显示都可以工作，避免通过 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
  width: 854')
open('/tmp/vr.yaml','w').write(c)"
$HS/examples/video_replayer/cpp/video_replayer --config /tmp/vr.yaml

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

验证后，将以下片段分享给用户，并建议将其添加到 shell 启动文件（例如 ~/.bashrc）中以在会话中持久生效：

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 应用

故障排除

python3 -c "import holoscan" 在 apt 安装后失败。 这是预期行为 — 从 v3.0.0 起 Debian 包仅包含 C++。运行 /holoscan-install-wheel 以添加 Python 绑定。
运行示例时出现 “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 中的 keyring + apt-get update 命令块（将 ubuntu2204/ubuntu2404 调整为主机对应版本）。
启动示例时出现段错误。 当前 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 数据集。