Installation de la roue Holoscan

Objectif

Installer les liaisons Python du SDK Holoscan via le fichier pip « holoscan-cu12 » / « holoscan-cu13 » dans un environnement virtuel, puis effectuer une vérification à l'aide des scripts « hello_world » et « video_replayer ».

Prérequis

• Système Linux x86_64 équipé d’un GPU NVIDIA et de son pilote (nvidia-smi).
• Kit d'outils CUDA dans le PATH correspondant à la version majeure de CUDA de l'hôte (12 ou 13).
• Python 3.10–3.13 avec venv disponible.
• Accès réseau à PyPI et à docs.nvidia.com.

Limitations

• Python uniquement. Pour les en-têtes/bibliothèques C++, à associer à /holoscan-install-debian.
• holoscan-cu12 et holoscan-cu13 s’excluent mutuellement — le fichier wheel doit correspondre au pilote CUDA de l’hôte.
• Les donnéesde video_replayer ne sont fournies qu’avec le paquet Debian ; en l’absence de celui-ci, définissez HOLOSCAN_INPUT_PATH sur un répertoire contenant racerx/.
• Il est recommandé d'exécuter `ulimit -s 32768 ` dans chaque shell exécutant Holoscan — sans cela, certaines applications génèrent un avertissement concernant la taille de la pile ou, dans de rares cas, une erreur de segmentation.

Étape 0 : Consultez les instructions d’installation officielles

Consultez toujours la section pip-wheel du site https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html avant l’installation. Extrait : noms exacts des paquets wheel (holoscan-cu12, holoscan-cu13), plage de versions Python prises en charge pour la version actuelle, prérequis devant figurer dans le PATH (CUDA Toolkit) et éventuels éléments supplémentaires facultatifs (versions spécifiques de LibTorch / ONNX Runtime). Si la documentation contredit l’une des informations ci-dessous, c’est la documentation qui prévaut.

Vous devez disposer de la variante CUDA déjà déterminée. Si vous ne la connaissez pas, exécutez d’abord la commande ` nvidia-smi 2>&1 | head -5 `.

Règle relative à la variante CUDA — choisissez le paquet pip :

Prérequis : CUDA Toolkit dans le PATH, Python 3.10–3.13. Options supplémentaires : LibTorch 2.11.0+, ONNX Runtime 1.22.0+.

Installez toujours le logiciel dans un environnement virtuel Python — cela évite les conflits avec les paquets système et est obligatoire sous Ubuntu 24.04 (qui bloque complètement l'utilisation de pip à l'échelle du système).

Étape 1 : Créer et activer l’environnement virtuel (venv)

Vérifiez d’abord s’il en existe déjà un :

ls ~/holoscan/venv 2>/dev/null && echo "existe" || echo "manquant"

S'il n'existe pas :

python3 -m venv ~/holoscan/venv

Puis activez-le :

source ~/holoscan/venv/bin/activate

Étape 2 : Installation

pip install holoscan-cu12   # ou holoscan-cu13

Étape 3 : Vérification

L'environnement venv doit être actif pour toutes les commandes ci-dessous.

# Importation de base — résultat attendu : chaîne de version, par ex. « 4.1.0 »
# L’avertissement RuntimeWarning relatif à la taille de la pile est sans conséquence ; la commande `ulimit -s 32768` permet de le désactiver.
python3 -c "import holoscan; print(holoscan.__version__)"

# Récupérer les exemples Python depuis GitHub à partir de la balise correspondant à la version installée.
# Il s’agit d’exemples officiels de NVIDIA, récupérés via HTTPS et associés à la balise
# correspondant au fichier wheel installé (v${SDK_VER}). Avant de les exécuter, prévenez l’utilisateur
# que vous êtes sur le point de télécharger et d’exécuter des scripts d’exemples à distance à partir de cette URL. Si
# il refuse ou si GitHub est inaccessible, passez directement à la consultation des exemples à l’étape 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 — résultat attendu : « 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 images, en mode sans interface graphique) — résultat attendu : « Exécution du graphe terminée. »
# Toujours exécuter en mode sans interface graphique : fonctionne avec ou sans écran, évite les défaillances de l’interface graphique via SSH.
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

Remarque : video_replayer a besoin des fichiers de données racerx. Ceux-ci sont fournis avec le paquet Debian dans /opt/nvidia/holoscan/data. Si le paquet Debian n’est pas installé, exécutez d’abord sudo /opt/nvidia/holoscan/examples/download_example_data (ce script nécessite l’installation du paquet apt), ou définissez HOLOSCAN_INPUT_PATH sur l’emplacement où se trouvent les données.

Étape 4 : Rappel à l'utilisateur

Il doit activer l’environnement venv à chaque nouvelle session de shell :

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # pour supprimer l'avertissement concernant la taille de la pile

Proposez ensuite les étapes suivantes :

• Découvrez des exemples Python sur https://github.com/nvidia-holoscan/holoscan-sdk/tree/v/examples
• Suivez pas à pas un exemple spécifique : /explain-example
• Commencez à créer une application Holoscan personnalisée

Dépannage

• Erreurs « externally-managed-environment » lors del’installation de pip install holoscan-cu12. Ubuntu 24.04 bloque pip à l’échelle du système. Créez et activez d’abord l’environnement venv de l’étape 1.
• ImportError / version CUDA incorrecte lors de l'importation de holoscan. La variante du fichier wheel ne correspond pas à la version CUDA de l'hôte. Désinstallez et réinstallez la version correspondante : pip uninstall -y holoscan-cu13 && pip install holoscan-cu12 (ou inversement).
• RuntimeWarning : taille de la pile… Sans conséquence, mais définissez ulimit -s 32768 dans le shell actuel pour faire taire ce message.
• Erreur de segmentation lors de l'exécution d'un exemple. ulimit -s 32768 n'a pas été défini. Définissez-le avant python3....
• video_replayer ne trouve pas racerx/. HOLOSCAN_INPUT_PATH ne pointe pas vers un répertoire le contenant. Installez le paquet Debian pour /opt/nvidia/holoscan/data, ou définissez HOLOSCAN_INPUT_PATH vers l'emplacement où se trouvent les données.
• source : fichier introuvable : ~/holoscan/venv/bin/activate dans un nouveau shell. Venv n’a pas été créé ou le chemin d’accès est incorrect. Relancez l’étape 1 ou corrigez le chemin d’accès.