Installation de la wheel pip Holoscan

Objectif

Installer les liaisons Python du SDK Holoscan via la wheel pip holoscan-cu12 / holoscan-cu13 dans un environnement virtuel, et vérifier avec hello_world et video_replayer.

Prérequis

• Linux x86_64 avec GPU NVIDIA + driver (nvidia-smi).
• CUDA Toolkit sur PATH correspondant à la version CUDA majeure 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 headers/libs C++, associez avec /holoscan-install-debian.
• holoscan-cu12 et holoscan-cu13 s'excluent mutuellement — la wheel doit correspondre au driver CUDA de l'hôte.
• Les données de video_replayer ne sont livrées qu'avec le package Debian ; sans lui, définissez HOLOSCAN_INPUT_PATH sur un répertoire contenant racerx/.
• ulimit -s 32768 est recommandé dans chaque shell exécutant Holoscan — sans cela, certaines applications émettent un avertissement de taille de pile ou, dans des cas plus rares, segfaultent.

Étape 0 : Consulter les Instructions d'Installation Officielles

Récupérez toujours la section pip-wheel de https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html avant d'installer. Extrayez : les noms exacts des packages wheel (holoscan-cu12, holoscan-cu13), la plage Python prise en charge pour la version actuelle, les prérequis qui doivent être sur PATH (CUDA Toolkit), et tout supplément facultatif (versions épinglées de LibTorch / ONNX Runtime). Si la documentation contredit quelque chose ci-dessous, la documentation a raison.

Vous avez besoin de la variante CUDA déjà déterminée. Si elle n'est pas connue, exécutez d'abord nvidia-smi 2>&1 | head -5.

Règle de variante CUDA — choisissez le package pip :

Prérequis : CUDA Toolkit sur PATH, Python 3.10–3.13. Suppléments facultatifs : LibTorch 2.11.0+, ONNX Runtime 1.22.0+.

Installez toujours dans un environnement virtuel Python — cela évite les conflits de packages système et est obligatoire sur Ubuntu 24.04 (qui bloque pip à l'échelle du système).

Étape 1 : Créer et Activer le venv

Vérifiez d'abord s'il en existe un :

ls ~/holoscan/venv 2>/dev/null && echo "exists" || echo "missing"

S'il manque :

python3 -m venv ~/holoscan/venv

Ensuite, activez :

source ~/holoscan/venv/bin/activate

Étape 2 : Installer

pip install holoscan-cu12   # ou holoscan-cu13

Étape 3 : Vérifier

Le venv doit être actif pour toutes les commandes ci-dessous.

# Import basique — attendu : chaîne de version, par ex. "4.1.0"
# L'avertissement RuntimeWarning concernant la taille de pile est inoffensif ; ulimit -s 32768 le supprime.
python3 -c "import holoscan; print(holoscan.__version__)"

# Récupérez les exemples Python depuis GitHub à la version de la wheel installée.
# Ce sont des exemples NVIDIA officiels, récupérés par HTTPS et épinglés au tag
# correspondant à la wheel installée (v${SDK_VER}). Avant de les exécuter, informez l'utilisateur
# que vous êtes sur le point de télécharger et d'exécuter des scripts d'exemples distants depuis cette URL. S'il décline
# ou que GitHub est inaccessible, passez à 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 — 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, sans affichage) — attendu : "Graph execution finished."
# Exécutez toujours sans affichage : fonctionne avec ou sans écran, évite les modes d'échec GUI par 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 livrés avec le package Debian à /opt/nvidia/holoscan/data. Si le package Debian n'est pas installé, exécutez d'abord sudo /opt/nvidia/holoscan/examples/download_example_data (nécessite que le package apt soit installé pour ce script), ou définissez HOLOSCAN_INPUT_PATH sur le répertoire où les données se trouvent.

Étape 4 : Rappeler à l'Utilisateur

Il doit activer le venv à chaque nouvelle session shell :

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

Ensuite, proposez les prochaines étapes :

• Explorer les exemples Python sur 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

• pip install holoscan-cu12 échoue avec "externally-managed-environment". Ubuntu 24.04 bloque pip à l'échelle du système. Créez et activez d'abord le venv depuis l'Étape 1.
• ImportError / CUDA incorrect au import holoscan. La variante de la wheel ne correspond pas à la CUDA de l'hôte. Désinstallez et réinstallez celle correspondante : pip uninstall -y holoscan-cu13 && pip install holoscan-cu12 (ou l'inverse).
• RuntimeWarning: stack size .... Inoffensif, mais définissez ulimit -s 32768 dans le shell courant pour le supprimer.
• Segmentation fault 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 package Debian pour /opt/nvidia/holoscan/data, ou définissez HOLOSCAN_INPUT_PATH sur le répertoire où les données se trouvent.
• source: no such file: ~/holoscan/venv/bin/activate dans un nouveau shell. Le venv n'a pas été créé ou le chemin est différent. Réexécutez l'Étape 1 ou corrigez le chemin.