Instalación de la rueda Holoscan

Objetivo

Instalar los enlaces de Python del SDK de Holoscan mediante el paquete pip «holoscan-cu12 » o «holoscan-cu13 » en un entorno virtual y comprobar su funcionamiento con «hello_world » y «video_replayer».

Requisitos previos

• Linux x86_64 con GPU NVIDIA + controlador (nvidia-smi).
• Kit de herramientas CUDA en la variable PATH que coincida con la versión principal de CUDA del host (12 o 13).
• Python 3.10–3.13 con venv disponible.
• Acceso a PyPI y docs.nvidia.com a través de la red.

Limitaciones

• Solo Python. Para encabezados y bibliotecas de C++, utilízalo junto con /holoscan-install-debian.
• holoscan-cu12 y holoscan-cu13 son mutuamente excluyentes: el archivo wheel debe coincidir con el controlador CUDA del sistema.
• Los datosde video_replayer solo se incluyen con el paquete de Debian; sin él, configura HOLOSCAN_INPUT_PATH en un directorio que contenga racerx/.
• Se recomienda ejecutar`ulimit -s 32768 ` en todos los shells que ejecuten Holoscan; sin ello, algunas aplicaciones emiten una advertencia sobre el tamaño de la pila o, en casos más excepcionales, dan un error de segmento.

Paso 0: Consulta las instrucciones oficiales de instalación

Consulta siempre la sección «pip-wheel» de https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html antes de instalar. Extrae: los nombres exactos de los paquetes wheel (holoscan-cu12, holoscan-cu13), el rango de versiones de Python compatible con la versión actual, los requisitos previos que deben estar en PATH (CUDA Toolkit) y cualquier extra opcional (versiones específicas de LibTorch / ONNX Runtime). Si la documentación discrepa de cualquier punto que se indique a continuación, prevalecerá la documentación.

Es necesario tener ya determinada la variante de CUDA. Si no la conoces, ejecuta primero nvidia-smi 2>&1 | head -5.

Regla para la variante de CUDA: elige el paquete de pip:

Requisitos previos: CUDA Toolkit en la variable PATH, Python 3.10–3.13. Extras opcionales: LibTorch 2.11.0+, ONNX Runtime 1.22.0+.

Instálalo siempre en un entorno virtual de Python: así se evitan conflictos con los paquetes del sistema y es obligatorio en Ubuntu 24.04 (que bloquea por completo el uso de pip en todo el sistema).

Paso 1: Crear y activar el entorno virtual (venv)

Comprueba primero si ya existe uno:

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

Si no existe:

python3 -m venv ~/holoscan/venv

A continuación, actívalo:

source ~/holoscan/venv/bin/activate

Paso 2: Instalar

pip install holoscan-cu12   # o holoscan-cu13

Paso 3: Verificar

El entorno venv debe estar activo para todos los comandos que aparecen a continuación.

# Importación básica — se espera: cadena de versión, p. ej., «4.1.0»
# La advertencia de tiempo de ejecución sobre el tamaño de la pila (RuntimeWarning) es inofensiva; se suprime con ulimit -s 32768.
python3 -c "import holoscan; print(holoscan.__version__)"

# Obtener ejemplos de Python de GitHub con la etiqueta de la versión instalada.
# Se trata de ejemplos oficiales de NVIDIA, obtenidos a través de HTTPS y vinculados a la etiqueta
# que coincide con el archivo wheel instalado (v${SDK_VER}). Antes de ejecutarlos, avisa al usuario
# que está a punto de descargar y ejecutar scripts de ejemplo remotos desde esta URL. Si
# se niega o no se puede acceder a GitHub, pasa directamente a explorar los ejemplos en el paso 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 — resultado esperado: «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 fotogramas, sin interfaz gráfica) — resultado esperado: "Ejecución del gráfico finalizada."
# Ejecutar siempre sin interfaz gráfica: funciona con o sin pantalla, evita los errores de la interfaz gráfica a través de 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

Nota: video_replayer necesita los archivos de datos de racerx. Estos se incluyen con el paquete de Debian en /opt/nvidia/holoscan/data. Si el paquete de Debian no está instalado, ejecuta primero `sudo /opt/nvidia/holoscan/examples/download_example_data ` (para este script es necesario que el paquete `apt` esté instalado), o configura `HOLOSCAN_INPUT_PATH ` con la ruta donde se encuentren los datos.

Paso 4: Recordatorio para el usuario

Debe activar el entorno venv en cada nueva sesión de terminal:

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # suprime la advertencia sobre el tamaño de la pila

A continuación, indícale los siguientes pasos:

• Explora los ejemplos de Python en https://github.com/nvidia-holoscan/holoscan-sdk/tree/v/examples
• Sigue paso a paso un ejemplo concreto: /explain-example
• Empieza a crear una aplicación personalizada de Holoscan

Solución de problemas

• Errores al ejecutar«pip install holoscan-cu12 » con «externally-managed-environment». Ubuntu 24.04 bloquea el uso de pip en todo el sistema. Crea y activa primero el entorno venv del paso 1.
• ImportError / CUDA incorrecta al importar holoscan. La variante del paquete wheel no coincide con la CUDA del host. Desinstala y vuelve a instalar la que coincida: pip uninstall -y holoscan-cu13 && pip install holoscan-cu12 (o viceversa).
• RuntimeWarning: tamaño de la pila... No es grave, pero configura «ulimit -s 32768» en el shell actual para que deje de aparecer.
• Error de segmentación al ejecutar un ejemplo. No se había establecido ulimit -s 32768. Configúralo antes de ejecutar python3....
• video_replayer no encuentra racerx/. HOLOSCAN_INPUT_PATH no apunta a un directorio que lo contenga. Instala el paquete de Debian para /opt/nvidia/holoscan/data, o configura HOLOSCAN_INPUT_PATH para que apunte a la ubicación donde se encuentren los datos.
• fuente: no existe tal archivo: ~/holoscan/venv/bin/activate en un nuevo shell. No se ha creado el entorno venv o la ruta es incorrecta. Vuelve a ejecutar el paso 1 o corrige la ruta.