holoscan-install-conda

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Holoscan Conda Installation

Holoscan的Conda安装

Purpose

用途

Install the Holoscan SDK (Python runtime and/or C++ dev headers) into a Conda environment on Linux x86_64, using conda-forge + rapidsai with a correctly pinned CUDA metapackage.

在Linux x86_64系统的Conda环境中，使用conda-forge + rapidsai源并正确固定CUDA元包，安装Holoscan SDK（Python运行时和/或C++开发头文件）。

Prerequisites

前提条件

Linux x86_64 with an NVIDIA GPU and CUDA 13 driver (check
```
nvidia-smi
```
).
```
conda
```
(Miniforge preferred). Step 1 installs it if missing.
Network access to conda-forge, rapidsai, and
```
docs.nvidia.com
```
.

带有NVIDIA GPU和CUDA 13驱动的Linux x86_64系统（可通过
```
nvidia-smi
```
命令检查）。
已安装
```
conda
```
（推荐使用Miniforge）。若未安装，步骤1会自动安装。
可访问conda-forge、rapidsai源以及
```
docs.nvidia.com
```
的网络权限。

Limitations

限制说明

CUDA 13 only (since v4.3.0 — earlier releases were CUDA 12). If the user has a CUDA 12 driver, redirect to
```
/holoscan-install-container
```
or
```
/holoscan-install-wheel
```
instead.
Linux x86_64 only — no aarch64/iGPU support on conda-forge.
```
ulimit -s 32768
```
is recommended in every shell that runs Holoscan — without it, some apps may segfault.

仅支持CUDA 13（从v4.3.0版本开始——早期版本支持CUDA 12）。如果用户使用的是CUDA 12驱动，请转至
```
/holoscan-install-container
```
或
```
/holoscan-install-wheel
```
页面。
仅支持Linux x86_64系统——conda-forge不支持aarch64/iGPU。
建议在所有运行Holoscan的Shell中执行
```
ulimit -s 32768
```
——否则部分应用可能会出现段错误。

Step 0: Consult the Official Install Instructions

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

Always fetch the current Conda section of

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

before installing — package names, channel selection, and the runtime/dev split can change between releases. Specifically extract:

The exact runtime package name (e.g.
```
holoscan
```
for Python bindings).
The C++ dev package name and whether the user needs it. As of v4.1.0,
```
libholoscan-dev
```
is a separate package containing headers and CMake config — install it whenever the user wants to develop C++ apps. Without it,
```
find_package(holoscan)
```
fails and there are no headers to
```
#include
```
.
Supported Python versions for the current release (3.10–3.13 for v4.3).
The current
```
cuda-version
```
pin (v4.3 →
```
13
```
).

rmm

and

ucxx

are distributed via the

rapidsai

channel;

holoscan

libholoscan

, and

libholoscan-dev

come from

conda-forge

If the doc disagrees with anything below, the doc wins — update the install commands accordingly and tell the user.

安装前请务必获取

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

中最新的Conda安装章节内容——不同版本之间，包名称、源选择以及运行时/开发包的划分可能会有所变化。需重点提取以下信息：

准确的运行时包名称（例如用于Python绑定的
```
holoscan
```
）。
C++开发包名称以及用户是否需要该包。从v4.1.0版本开始，
```
libholoscan-dev
```
是包含头文件和CMake配置的独立包——用户若要开发C++应用则需安装该包。若未安装，
```
find_package(holoscan)
```
会执行失败，且无法通过
```
#include
```
引入头文件。
当前版本支持的Python版本（v4.3支持3.10–3.13）。
当前需固定的
```
cuda-version
```
版本（v4.3对应
```
13
```
）。

rmm

和

ucxx

通过

rapidsai

源分发；

holoscan

、

libholoscan

和

libholoscan-dev

来自

conda-forge

源。

若本文档内容与官方文档不符，以官方文档为准——请据此更新安装命令并告知用户。

Step 1: Prerequisites Check

步骤1：检查前提条件

bash

conda --version 2>&1
nvidia-smi 2>&1 | head -5

conda

is not found, install Miniforge silently (preferred over Miniconda for conda-forge):

bash

wget -q https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O /tmp/Miniforge3.sh
bash /tmp/Miniforge3.sh -b -p ~/miniforge3
source ~/miniforge3/etc/profile.d/conda.sh
conda --version

The

-b

flag installs non-interactively without modifying

.bashrc

. Users must

source ~/miniforge3/etc/profile.d/conda.sh

in each new shell (or add it to their shell RC file) to make

conda

available.

bash

conda --version 2>&1
nvidia-smi 2>&1 | head -5

若未找到

conda

命令，请静默安装Miniforge（相较于Miniconda，更推荐使用Miniforge以适配conda-forge）：

bash

wget -q https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O /tmp/Miniforge3.sh
bash /tmp/Miniforge3.sh -b -p ~/miniforge3
source ~/miniforge3/etc/profile.d/conda.sh
conda --version

-b

参数表示非交互式安装，且不会修改

.bashrc

文件。用户需在每个新Shell中执行

source ~/miniforge3/etc/profile.d/conda.sh

（或将其添加到Shell的RC文件中），才能使用

conda

命令。

Step 2: Create Environment and Install

步骤2：创建环境并安装

Package roles

包角色说明

```
libholoscan
```
— C++ runtime symbols (
```
libholoscan_core.so
```
). Auto-pulled as a dependency.
```
holoscan
```
— Python bindings.

libholoscan-dev

— C++ headers,

libholoscan_core.so

symlink, and

holoscan-config.cmake

for

find_package(holoscan)

```
rmm
```
— RAPIDS Memory Manager (rapidsai channel). Undeclared runtime dep of
```
holoscan
```
;
```
import holoscan
```
fails without it.
```
ucxx
```
— UCX Python bindings (rapidsai channel), needed for distributed/multi-process apps.
```
cuda-version=13
```
— pins the CUDA 13 metapackage so the solver picks compatible CUDA runtime libs.

Create the environment first:

bash

source ~/miniforge3/etc/profile.d/conda.sh   # if conda not yet on PATH
conda create -n holoscan python=3.13 -y
conda activate holoscan

Then pick one of the variants below based on the user's goal.

Pick the packages for the user's goal — Python-only needs

holoscan

, C++ dev needs

libholoscan-dev

, both works for combined use:

bash

conda install <packages> rmm ucxx cuda-version=13 -c rapidsai -c conda-forge -y

For C++ development, also install the toolchain:

bash

conda install -c conda-forge cxx-compiler cmake ninja -y

Verify Python installs with

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

. Verify C++ dev installs with

ls "$CONDA_PREFIX/include/holoscan"

```
libholoscan
```
—— C++运行时符号文件（
```
libholoscan_core.so
```
），会作为依赖自动安装。
```
holoscan
```
—— Python绑定包。

libholoscan-dev

—— C++头文件、

libholoscan_core.so

符号链接以及用于

find_package(holoscan)

的

holoscan-config.cmake

配置文件。

```
rmm
```
—— RAPIDS内存管理器（来自rapidsai源），是
```
holoscan
```
未声明的运行时依赖；若未安装，
```
import holoscan
```
会执行失败。
```
ucxx
```
—— UCX Python绑定包（来自rapidsai源），用于分布式/多进程应用。
```
cuda-version=13
```
—— 固定CUDA 13元包，确保包管理器选择兼容的CUDA运行时库。

首先创建环境：

bash

source ~/miniforge3/etc/profile.d/conda.sh   # 若conda未添加到PATH
conda create -n holoscan python=3.13 -y
conda activate holoscan

然后根据用户需求选择以下安装变体之一。

根据用户目标选择对应包——仅Python开发需安装

holoscan

，C++开发需安装

libholoscan-dev

，两者都安装则支持混合开发：

bash

conda install <packages> rmm ucxx cuda-version=13 -c rapidsai -c conda-forge -y

若进行C++开发，还需安装工具链：

bash

conda install -c conda-forge cxx-compiler cmake ninja -y

验证Python安装：执行

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

。验证C++开发安装：执行

ls "$CONDA_PREFIX/include/holoscan"

。

Step 3: Run Python Tests

步骤3：运行Python测试

ulimit -s 32768

is recommended — without it, some Holoscan apps may segfault on startup.

video_replayer

is a display app that loops forever by default. Always patch its YAML to stop after 10 frames (

count: 10

repeat: false

realtime: false

) and to run headless (

headless: true

) — headless works with or without a display attached and avoids GUI failure modes over SSH, so we don't branch on

$DISPLAY

Download scripts and YAML configs, patch the YAML, then run:

bash

source ~/miniforge3/etc/profile.d/conda.sh
conda activate holoscan
ulimit -s 32768

SDK_VER=$(python3 -c "import holoscan; print(holoscan.__version__)")
BASE="https://raw.githubusercontent.com/nvidia-holoscan/holoscan-sdk/v${SDK_VER}/examples"

curl -fsSL "${BASE}/hello_world/python/hello_world.py"         -o /tmp/hs_hello_world.py
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/video_replayer.yaml

建议执行

ulimit -s 32768

——否则部分Holoscan应用启动时可能会出现段错误。

video_replayer

是一个默认无限循环的显示应用。需修改其YAML配置文件，使其在播放10帧后停止（

count: 10

、

repeat: false

、

realtime: false

），并以无头模式运行（

headless: true

）——无头模式无论是否连接显示器都能正常工作，且可避免SSH连接时的GUI故障，因此无需根据

$DISPLAY

变量进行分支处理。

下载脚本和YAML配置文件，修改YAML配置后运行：

bash

source ~/miniforge3/etc/profile.d/conda.sh
conda activate holoscan
ulimit -s 32768

SDK_VER=$(python3 -c "import holoscan; print(holoscan.__version__)")
BASE="https://raw.githubusercontent.com/nvidia-holoscan/holoscan-sdk/v${SDK_VER}/examples"

curl -fsSL "${BASE}/hello_world/python/hello_world.py"         -o /tmp/hs_hello_world.py
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/video_replayer.yaml

Patch video_replayer.yaml — 10 frames, headless.

修改video_replayer.yaml配置——播放10帧，无头模式。

python3 -c " c = open('/tmp/video_replayer.yaml').read() c = c.replace('count: 0', 'count: 10') c = c.replace('repeat: true', 'repeat: false') c = c.replace('realtime: true', 'realtime: false') c = c.replace(' width: 854', ' headless: true\n width: 854') open('/tmp/video_replayer.yaml', 'w').write(c)"

hello_world — no display, no data needed; expected: "Hello World!"

hello_world——无需显示器和数据；预期输出："Hello World!"

python3 /tmp/hs_hello_world.py

video_replayer — needs racerx data; expected: frames rendered, "Graph execution finished."

video_replayer——需要racerx数据；预期输出：渲染完成，"Graph execution finished."

HOLOSCAN_INPUT_PATH=/path/to/holoscan/data python3 /tmp/hs_video_replayer.py


`HOLOSCAN_INPUT_PATH` must point to the directory containing a `racerx/` subdirectory.
If the user has the SDK source repo that is `~/repos/holoscan-sdk/data`; otherwise download
with the `download_ngc_data` script from the Debian or source install tree.

HOLOSCAN_INPUT_PATH=/path/to/holoscan/data python3 /tmp/hs_video_replayer.py


`HOLOSCAN_INPUT_PATH`必须指向包含`racerx/`子目录的文件夹。若用户已下载SDK源码仓库，则路径为`~/repos/holoscan-sdk/data`；否则可从Debian包或源码安装目录中使用`download_ngc_data`脚本下载数据。

Step 4: Remind the User

步骤4：提醒用户

They must do the following in each new shell session:

bash

source ~/miniforge3/etc/profile.d/conda.sh   # if Miniforge was installed with -b
conda activate holoscan
ulimit -s 32768   # recommended — prevents segfaults in some apps

Consider adding these lines to

~/.bashrc

~/.zshrc

to avoid repeating them.

Then offer next steps:

Explore C++ and 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 ~/miniforge3/etc/profile.d/conda.sh   # 若Miniforge使用-b参数安装
conda activate holoscan
ulimit -s 32768   # 推荐执行——避免部分应用出现段错误

建议将这些命令添加到

~/.bashrc

或

~/.zshrc

文件中，避免重复执行。

然后可为用户提供后续操作建议：

浏览C++和Python示例：

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

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

Troubleshooting

故障排查

ImportError: librmm.so: cannot open shared object file
.
```
rmm
```
was not installed. Re-run the Step 2
```
conda install
```
line —
```
rmm
```
is an undeclared runtime dependency of
```
holoscan
```
.
Solver picks an older
holoscan
build than expected. Channel order may be wrong. Use
```
-c rapidsai -c conda-forge
```
(rapidsai first) — that's the order in the official install command, and under strict channel priority a conda-forge-first ordering can lock the solver to an older
```
holoscan
```
build.
Segmentation fault on app startup. Set
```
ulimit -s 32768
```
in the current shell before running any Holoscan app. Not all apps trip this, but the larger stack avoids the failure mode.
find_package(holoscan)
fails when building C++ apps. Install
```
libholoscan-dev
```
(headers + CMake config are in a separate package since v4.1.0).
conda: command not found
in a new shell. Miniforge was installed with
```
-b
```
and did not patch
```
.bashrc
```
. Run
```
source ~/miniforge3/etc/profile.d/conda.sh
```
or add it to your shell RC file.

ImportError: librmm.so: cannot open shared object file
：未安装
```
rmm
```
包。重新执行步骤2中的
```
conda install
```
命令——
```
rmm
```
是
```
holoscan
```
未声明的运行时依赖。
包管理器选择的
holoscan
版本比预期旧：源顺序可能有误。请使用
```
-c rapidsai -c conda-forge
```
（rapidsai在前）——这是官方安装命令中的源顺序；若使用conda-forge优先的顺序，在严格源优先级设置下，包管理器可能会锁定到旧版本的
```
holoscan
```
。
应用启动时出现段错误：在运行Holoscan应用前，在当前Shell中执行
```
ulimit -s 32768
```
。并非所有应用都会触发此问题，但增大栈空间可避免该故障。
构建C++应用时
find_package(holoscan)
执行失败：安装
```
libholoscan-dev
```
包（从v4.1.0版本开始，头文件和CMake配置位于独立包中）。
新Shell中提示
conda: command not found
：Miniforge使用
```
-b
```
参数安装，未修改
```
.bashrc
```
文件。执行
```
source ~/miniforge3/etc/profile.d/conda.sh
```
或将其添加到Shell的RC文件中。