Installation Holoscan via Conda

Objectif

Installer le SDK Holoscan (runtime Python et/ou en-têtes de développement C++) dans un environnement Conda sous Linux x86_64, en utilisant conda-forge + rapidsai avec un metapackage CUDA correctement épinglé.

Prérequis

Linux x86_64 avec un GPU NVIDIA et driver CUDA 13 (vérifier avec nvidia-smi).
conda (Miniforge préféré). L'étape 1 l'installe en cas d'absence.
Accès réseau à conda-forge, rapidsai et docs.nvidia.com.

Limitations

CUDA 13 uniquement (depuis v4.3.0 — les versions antérieures utilisaient CUDA 12). Si l'utilisateur dispose d'un driver CUDA 12, le rediriger vers /holoscan-install-container ou /holoscan-install-wheel.
Linux x86_64 uniquement — pas de support aarch64/iGPU sur conda-forge.
ulimit -s 32768 est recommandé dans chaque shell exécutant Holoscan — sans cela, certaines applications peuvent segfaulter.

Étape 0 : Consulter les instructions officielles d'installation

Toujours récupérer la section Conda actuelle de https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html avant d'installer — les noms de packages, la sélection des canaux et la séparation runtime/dev peuvent changer entre les versions. Extraire spécifiquement :

Le nom exact du package runtime (ex. holoscan pour les bindings Python).
Le nom du package C++ dev et si l'utilisateur en a besoin. À partir de v4.1.0, libholoscan-dev est un package séparé contenant les en-têtes et la config CMake — l'installer chaque fois que l'utilisateur souhaite développer des apps C++. Sans lui, find_package(holoscan) échoue et il n'y a pas d'en-têtes à #include.
Les versions Python supportées pour la version actuelle (3.10–3.13 pour v4.3).
L'épinglage cuda-version actuel (v4.3 → 13).

rmm et ucxx sont distribués via le canal rapidsai ; holoscan, libholoscan et libholoscan-dev proviennent de conda-forge.

Si la documentation contredit quelque chose ci-dessous, la documentation a raison — mettre à jour les commandes d'installation en conséquence et en informer l'utilisateur.

Étape 1 : Vérification des prérequis

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

Si conda n'est pas trouvé, installer Miniforge en mode silencieux (préféré à Miniconda pour conda-forge) :

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

Le flag -b installe de manière non-interactive sans modifier .bashrc. Les utilisateurs doivent exécuter source ~/miniforge3/etc/profile.d/conda.sh dans chaque nouveau shell (ou l'ajouter à leur fichier RC) pour rendre conda disponible.

Étape 2 : Créer l'environnement et installer

Rôles des packages

libholoscan — symboles runtime C++ (libholoscan_core.so). Tiré automatiquement comme dépendance.
holoscan — bindings Python.
libholoscan-dev — en-têtes C++, symlink libholoscan_core.so et holoscan-config.cmake pour find_package(holoscan).
rmm — RAPIDS Memory Manager (canal rapidsai). Dépendance runtime non déclarée de holoscan ; import holoscan échoue sans lui.
ucxx — bindings Python UCX (canal rapidsai), nécessaire pour les apps distribuées/multi-processus.
cuda-version=13 — épingle le metapackage CUDA 13 pour que le solveur choisisse les libs runtime CUDA compatibles.

Créer d'abord l'environnement :

source ~/miniforge3/etc/profile.d/conda.sh   # si conda n'est pas encore sur PATH
conda create -n holoscan python=3.13 -y
conda activate holoscan

Puis choisir l'une des variantes ci-dessous selon l'objectif de l'utilisateur.

Sélectionner les packages selon l'objectif de l'utilisateur — Python seul nécessite holoscan, développement C++ nécessite libholoscan-dev, les deux fonctionnent pour un usage combiné :

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

Pour le développement C++, installer également la chaîne d'outils :

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

Vérifier l'installation Python avec python3 -c "import holoscan; print(holoscan.__version__)". Vérifier l'installation C++ dev avec ls "$CONDA_PREFIX/include/holoscan".

Étape 3 : Exécuter les tests Python

ulimit -s 32768 est recommandé — sans cela, certaines apps Holoscan peuvent segfaulter au démarrage.

video_replayer est une app d'affichage qui boucle indéfiniment par défaut. Toujours patcher son YAML pour s'arrêter après 10 frames (count: 10, repeat: false, realtime: false) et s'exécuter sans interface graphique (headless: true) — headless fonctionne avec ou sans affichage attaché et évite les modes de défaillance GUI via SSH, donc on ne branch pas sur $DISPLAY.

Télécharger les scripts et configs YAML, patcher le YAML, puis exécuter :

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

# Patcher video_replayer.yaml — 10 frames, headless.
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 — pas d'affichage, pas de données nécessaires ; attendu : "Hello World!"
python3 /tmp/hs_hello_world.py

# video_replayer — nécessite les données racerx ; attendu : frames rendues, "Graph execution finished."
HOLOSCAN_INPUT_PATH=/path/to/holoscan/data python3 /tmp/hs_video_replayer.py

HOLOSCAN_INPUT_PATH doit pointer vers le répertoire contenant un sous-répertoire racerx/. Si l'utilisateur possède le repo source SDK, c'est ~/repos/holoscan-sdk/data ; sinon, télécharger avec le script download_ngc_data de l'arborescence d'installation Debian ou source.

Étape 4 : Rappeler à l'utilisateur

Il doit faire ce qui suit dans chaque nouvelle session shell :

source ~/miniforge3/etc/profile.d/conda.sh   # si Miniforge a été installé avec -b
conda activate holoscan
ulimit -s 32768   # recommandé — prévient les segfaults dans certaines apps

Envisager d'ajouter ces lignes à ~/.bashrc ou ~/.zshrc pour éviter de les répéter.

Puis proposer les prochaines étapes :

Explorer les exemples C++ et Python à https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples
Parcourir un exemple spécifique : /explain-example
Commencer à construire une application Holoscan personnalisée

Dépannage

ImportError: librmm.so: cannot open shared object file. rmm n'a pas été installé. Réexécuter la ligne conda install de l'étape 2 — rmm est une dépendance runtime non déclarée de holoscan.
Le solveur choisit une version antérieure de holoscan qu'attendu. L'ordre des canaux peut être incorrect. Utiliser -c rapidsai -c conda-forge (rapidsai en premier) — c'est l'ordre dans la commande d'installation officielle, et avec une priorité de canal stricte, un ordre conda-forge-first peut verrouiller le solveur sur une version antérieure de holoscan.
Segmentation fault au démarrage de l'app. Définir ulimit -s 32768 dans le shell actuel avant d'exécuter toute app Holoscan. Pas toutes les apps déclenchent ceci, mais la pile plus grande évite ce mode de défaillance.
find_package(holoscan) échoue lors de la construction d'apps C++. Installer libholoscan-dev (les en-têtes et la config CMake sont dans un package séparé depuis v4.1.0).
conda: command not found dans un nouveau shell. Miniforge a été installé avec -b et n'a pas patché .bashrc. Exécuter source ~/miniforge3/etc/profile.d/conda.sh ou l'ajouter à votre fichier RC shell.

holoscan-install-conda