Instalação da roda do Holoscan

Objetivo

Instalar as ligações Python do SDK do Holoscan por meio do pacote pip holoscan-cu12 / holoscan-cu13 em um ambiente virtual e verificar com os programas hello_world e video_replayer.

Pré-requisitos

• Linux x86_64 com GPU NVIDIA + driver (nvidia-smi).
• CUDA Toolkit no PATH compatível com a versão principal do CUDA do host (12 ou 13).
• Python 3.10–3.13 com venv disponível.
• Acesso à rede para PyPI e docs.nvidia.com.

Limitações

• Apenas Python. Para cabeçalhos/bibliotecas C++, use em conjunto com /holoscan-install-debian.
• O holoscan-cu12 e o holoscan-cu13 são mutuamente exclusivos — o wheel deve corresponder ao driver CUDA do host.
• Os dadosdo video_replayer vêm apenas com o pacote Debian; sem ele, defina HOLOSCAN_INPUT_PATH para um diretório que contenha racerx/.
• Recomenda-se usar`ulimit -s 32768` em todos os shells que executam o Holoscan — sem isso, alguns aplicativos exibem um aviso sobre o tamanho da pilha ou, em casos mais raros, apresentam falha de segmentação.

Passo 0: Consulte as instruções oficiais de instalação

Sempre consulte a seção pip-wheel do site https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html antes de instalar. Extraia: nomes exatos dos pacotes wheel (holoscan-cu12, holoscan-cu13), a versão do Python compatível com a versão atual, pré-requisitos que devem estar no PATH (CUDA Toolkit) e quaisquer extras opcionais (versões fixas do LibTorch / ONNX Runtime). Se a documentação contradizer qualquer informação abaixo, a documentação prevalece.

É necessário que a variante CUDA já esteja definida. Caso não seja conhecida, execute primeiro o comando ` nvidia-smi 2>&1 | head -5 `.

Regra para a variante CUDA — escolha o pacote pip:

Pré-requisitos: CUDA Toolkit no PATH, Python 3.10–3.13. Extras opcionais: LibTorch 2.11.0+, ONNX Runtime 1.22.0+.

Sempre instale em um ambiente virtual do Python — isso evita conflitos com pacotes do sistema e é obrigatório no Ubuntu 24.04 (que bloqueia totalmente o uso do pip em todo o sistema).

Passo 1: Criar e ativar o venv

Verifique primeiro se já existe um:

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

Se não houver:

python3 -m venv ~/holoscan/venv

Em seguida, ative:

source ~/holoscan/venv/bin/activate

Passo 2: Instalar

pip install holoscan-cu12   # ou holoscan-cu13

Etapa 3: Verificar

O venv deve estar ativo para todos os comandos abaixo.

# Importação básica — esperado: string da versão, por exemplo, "4.1.0"
# O RuntimeWarning relacionado ao tamanho da pilha é inofensivo; o comando `ulimit -s 32768` o suprime.
python3 -c "import holoscan; print(holoscan.__version__)"

# Baixe exemplos em Python do GitHub na tag da versão instalada.
# Estes são exemplos oficiais da NVIDIA, baixados via HTTPS e vinculados à tag
# que corresponde ao wheel instalado (v${SDK_VER}). Antes de executá-los, avise ao usuário
# que você está prestes a baixar e executar scripts de exemplo remotos a partir desta URL. Se
# ele recusar ou se o GitHub estiver inacessível, pule para a visualização dos exemplos na Etapa 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 — 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 quadros, modo headless) — esperado: "Execução do gráfico concluída."
# Sempre execute sem interface gráfica: funciona com ou sem monitor, evita falhas da GUI 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

Observação: o video_replayer precisa dos arquivos de dados do racerx. Eles vêm com o pacote Debian em /opt/nvidia/holoscan/data. Se o pacote Debian não estiver instalado, execute primeiro o comando `sudo /opt/nvidia/holoscan/examples/download_example_data` (isso requer que o pacote `apt` esteja instalado para que o script funcione) ou defina `HOLOSCAN_INPUT_PATH ` para o local onde os dados estão armazenados.

Etapa 4: Lembre o usuário

É necessário ativar o venv em cada nova sessão do shell:

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # suprime o aviso sobre o tamanho da pilha

Em seguida, sugira os próximos passos:

• Explore exemplos em Python em https://github.com/nvidia-holoscan/holoscan-sdk/tree/v/examples
• Siga passo a passo um exemplo específico: /explain-example
• Comece a criar um aplicativo Holoscan personalizado

Solução de problemas

• O comando`pip install holoscan-cu12 ` apresenta erros com “externally-managed-environment”. O Ubuntu 24.04 bloqueia o pip em todo o sistema. Primeiro, crie e ative o venv da Etapa 1.
• ImportError / CUDA incorreto na importação do holoscan. A variante do wheel não corresponde ao CUDA do host. Desinstale e reinstale a versão compatível: pip uninstall -y holoscan-cu13 && pip install holoscan-cu12 (ou vice-versa).
• RuntimeWarning: tamanho da pilha .... Inofensivo, mas defina ulimit -s 32768 no shell atual para silenciar o aviso.
• Falha de segmentação ao executar um exemplo. O `ulimit -s 32768 ` não foi definido. Defina-o antes de executar o python3 ....
• O `video_replayer` não consegue encontrar o `racerx/`. A variável HOLOSCAN_INPUT_PATH não está apontando para um diretório que o contenha. Instale o pacote Debian para /opt/nvidia/holoscan/data ou defina HOLOSCAN_INPUT_PATH para o local onde os dados estão armazenados.
• source: arquivo inexistente: ~/holoscan/venv/bin/activate em um novo shell. O venv não foi criado ou o caminho está incorreto. Execute novamente a Etapa 1 ou corrija o caminho.