holoscan-install-wheel

Holoscan pip ホイールのインストール

目的

holoscan-cu12 / holoscan-cu13 の pip ホイールを仮想環境にインストールして Holoscan SDK の Python バインディングを使用できるようにし、hello_world と video_replayer で動作を確認します。

前提条件

• NVIDIA GPU とドライバーを搭載した Linux x86_64（nvidia-smi）。
• ホストの CUDA メジャーバージョン（12 または 13）に一致する CUDA Toolkit が PATH に設定されていること。
• venv が利用可能な Python 3.10～3.13。
• PyPI および docs.nvidia.com へのネットワークアクセス。

制限事項

• Python のみが対象です。C++ ヘッダー／ライブラリを使用する場合は、/holoscan-install-debian と組み合わせてください。
• holoscan-cu12 と holoscan-cu13 は同時に使用できません。ホイールはホストの CUDA ドライバーに一致している必要があります。
• video_replayer のデータは Debian パッケージにのみ含まれています。データがない場合は、HOLOSCAN_INPUT_PATH に racerx/ を含むディレクトリを設定してください。
• Holoscan を実行する各シェルで ulimit -s 32768 を設定することを推奨します。設定しない場合、一部のアプリでスタックサイズの警告が表示されたり、まれにセグメンテーション違反が発生したりします。

ステップ 0：公式のインストール手順を確認する

インストール前に、必ず https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html の pip ホイールに関するセクションを取得してください。次の情報を確認します。正確なホイールパッケージ名（holoscan-cu12、holoscan-cu13）、現在のリリースでサポートされている Python のバージョン範囲、PATH に設定が必要な前提条件（CUDA Toolkit）、任意の追加パッケージ（LibTorch／ONNX Runtime のバージョン指定）。ドキュメントの内容が以下と異なる場合は、ドキュメントを優先してください。

使用する CUDA バリアントは事前に決定しておく必要があります。不明な場合は、最初に nvidia-smi 2>&1 | head -5 を実行してください。

CUDA バリアントのルール — pip パッケージを選択します：

nvidia-smi の CUDA バージョン	pip パッケージ
13.x 以上	holoscan-cu13
12.x（すべての GPU）	holoscan-cu12

前提条件：CUDA Toolkit が PATH に設定されていること、Python 3.10～3.13。任意の追加パッケージ：LibTorch 2.11.0 以上、ONNX Runtime 1.22.0 以上。

必ず Python 仮想環境にインストールしてください。これによりシステムパッケージとの競合を避けられます。また、Ubuntu 24.04 ではシステム全体への pip インストールがブロックされるため、仮想環境が必須です。

ステップ 1：venv を作成して有効化する

最初に、既存の環境があるか確認します。

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

ない場合は、次を実行します。

python3 -m venv ~/holoscan/venv

次に、有効化します。

source ~/holoscan/venv/bin/activate

ステップ 2：インストールする

pip install holoscan-cu12   # or holoscan-cu13

ステップ 3：動作を確認する

以下のすべてのコマンドを実行する前に、venv を有効化してください。

# Basic import — expected: version string, e.g. "4.1.0"
# The stack-size RuntimeWarning is harmless; ulimit -s 32768 suppresses it.
python3 -c "import holoscan; print(holoscan.__version__)"

# Fetch Python examples from GitHub at the installed version tag.
# These are official NVIDIA examples, fetched over HTTPS and pinned to the tag
# matching the installed wheel (v${SDK_VER}). Before running them, tell the user
# you're about to download and execute remote example scripts from this URL. If
# they decline or GitHub is unreachable, skip to browsing the examples in Step 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 — expected: "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 frames, headless) — expected: "Graph execution finished."
# Always run headless: works with or without a display, avoids GUI failure modes over 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

注：video_replayer には racerx データファイルが必要です。このファイルは Debian パッケージの /opt/nvidia/holoscan/data に含まれています。Debian パッケージがインストールされていない場合は、最初に sudo /opt/nvidia/holoscan/examples/download_example_data を実行してください（このスクリプトの実行には apt パッケージのインストールが必要です）。または、データがある場所を HOLOSCAN_INPUT_PATH に設定してください。

ステップ 4：ユーザーに伝える

新しいシェルセッションを開始するたびに、venv を有効化する必要があります。

source ~/holoscan/venv/bin/activate
ulimit -s 32768   # suppress stack-size warning

次に、以下の手順を案内します。

• https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples で Python の例を確認する
• 特定の例について詳しく説明する：/explain-example
• 独自の Holoscan アプリケーションの開発を始める

トラブルシューティング

• pip install holoscan-cu12 で「externally-managed-environment」エラーが発生する。 Ubuntu 24.04 ではシステム全体への pip インストールがブロックされます。最初にステップ 1 の手順で venv を作成して有効化してください。
• import holoscan 時に ImportError が発生する／CUDA が一致しない。 ホイールのバリアントがホストの CUDA と一致していません。該当するバリアントをアンインストールして再インストールしてください：pip uninstall -y holoscan-cu13 && pip install holoscan-cu12（またはその逆）。
• RuntimeWarning: stack size ... が表示される。 無害ですが、警告を抑制するには現在のシェルで ulimit -s 32768 を設定してください。
• 例の実行時にセグメンテーション違反が発生する。 ulimit -s 32768 が設定されていません。python3 ... を実行する前に設定してください。
• video_replayer が racerx/ を見つけられない。 HOLOSCAN_INPUT_PATH が、そのディレクトリを含む場所を指していません。/opt/nvidia/holoscan/data を利用するには Debian パッケージをインストールするか、データがある場所を HOLOSCAN_INPUT_PATH に設定してください。
• 新しいシェルで source: no such file: ~/holoscan/venv/bin/activate が表示される。 venv が作成されていないか、パスが異なります。ステップ 1 を再実行するか、パスを修正してください。