holoscan-install-debian

Holoscan Debian/apt インストール

目的

NVIDIA の apt リポジトリを使用して Ubuntu に Holoscan SDK の C++ ランタイムとヘッダーをインストールし、ホストの CUDA ドライバーに適した holoscan-cuda-* パッケージを選択して、同梱の C++ サンプルで動作を確認します。

前提条件

• NVIDIA GPU と動作するドライバー（nvidia-smi）を備えた Ubuntu x86_64（22.04 / 24.04）または ARM64（Jetson / IGX）。
• sudo と、developer.download.nvidia.com および docs.nvidia.com へのネットワークアクセス。
• cuda-keyring パッケージ（インストールされていない場合はステップ 2 でインストールします）。

制限事項

• apt から Python バインディングはインストールできません。Python が必要な場合は /holoscan-install-wheel を併用してください。
• Ubuntu 専用です。他のディストリビューションでは、コンテナーまたは wheel によるインストールを使用してください。
• パッケージの種類はホストの CUDA ドライバーに適合している必要があります（holoscan-cuda-12 と holoscan-cuda-13）。種類が間違っていると、「CUDA driver version is insufficient」と表示されます。

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

インストール前に、https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html の Debian/apt セクションを取得してください。次の情報を抽出します。

• 正確なパッケージ名（holoscan-cuda-12、holoscan-cuda-13、holoscan）
• サポート対象の Ubuntu バージョン
• 対象のディストリビューションに適した cuda-keyring の URL

ドキュメントの内容が以下と異なる場合は、ドキュメントを優先してください。

OS のバージョンと CUDA の種類がまだ分からない場合は、並列で実行します。

lsb_release -a 2>/dev/null || cat /etc/os-release
nvidia-smi 2>&1 | head -5

CUDA の種類のルール — apt パッケージを選択してください：

nvidia-smi の CUDA Version	パッケージ
13.x+	holoscan-cuda-13
12.x（IGX の場合）	holoscan
12.x（IGX 以外の場合）	holoscan-cuda-12
12.x（nvgpu の場合）	holoscan-cuda-12

ステップ 1：前提条件の確認

dpkg -l | grep cuda-keyring
dpkg -l | grep -E "holoscan-cuda-(12|13)|^ii  holoscan "
apt-cache show holoscan-cuda-13 holoscan-cuda-12 2>/dev/null | grep -E "^(Package|Version)"

ステップ 1 の確認結果に基づく判断ルール：

• cuda-keyring がすでにインストールされている場合は、キーリングの手順を省略します。
• リポジトリがすでに設定されており、パッケージが apt-cache show で見つかる場合は、apt-get update を省略します。
• 対象のパッケージの種類がすでにインストールされている場合（例：cu12 を対象とする場合の holoscan-cuda-12）、ステップ 2 全体を省略し、ステップ 3 に直接進みます。

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

ステップ 1 でパッケージがすでにインストールされていると確認できた場合、またはユーザーが IGX プラットフォームを使用している場合は、このステップを省略します。

# If cuda-keyring missing (adjust ubuntu2204/ubuntu2404 as needed) and not on IGX platform:
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb && sudo apt-get update

sudo apt-get install -y holoscan-cuda-12   # or holoscan-cuda-13

ステップ 3：確認

このステップの残りで使用する環境変数を一度設定してから、3 つの C++ チェックを実行します。

HS=/opt/nvidia/holoscan
export LD_LIBRARY_PATH=$HS/lib
export HOLOSCAN_INPUT_PATH=$HS/data
ulimit -s 32768

ls $HS/examples/{hello_world,tensor_interop,video_replayer}/

# hello_world — expected: "Hello World!"
$HS/examples/hello_world/cpp/hello_world

# tensor_interop — expected: tensors doubling each pass, "Graph execution finished."
# If "CUDA driver version is insufficient": swap package variant:
#   sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12
$HS/examples/tensor_interop/cpp/tensor_interop

# video_replayer (10 frames, headless) — expected: Vulkan selects NVIDIA GPU, "Graph execution finished."
# Always run headless: works with or without a display, avoids GUI failure modes over SSH.
ls $HS/data/racerx 2>/dev/null || sudo $HS/examples/download_example_data
python3 -c "
c=open('$HS/examples/video_replayer/cpp/video_replayer.yaml').read()
c=c.replace('count: 0','count: 10').replace('repeat: true','repeat: false').replace('realtime: true','realtime: false')
c=c.replace('  width: 854','  headless: true\n  width: 854')
open('/tmp/vr.yaml','w').write(c)"
$HS/examples/video_replayer/cpp/video_replayer --config /tmp/vr.yaml

ステップ 4：再利用可能な環境設定スニペットをユーザーに提示する

確認できたら、このスニペットをユーザーに共有し、セッションをまたいで設定を保持したい場合は、シェルの起動ファイル（例：~/.bashrc）に追加することを提案します。

export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib:${LD_LIBRARY_PATH}
export HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data
ulimit -s 32768

続けて、次のステップを提案します。

• Python サポートを追加する：/holoscan-install-wheel
• サンプルを確認する：ls /opt/nvidia/holoscan/examples/
• 特定のサンプルについて説明する：/explain-example
• カスタム Holoscan アプリケーションの構築を開始する

トラブルシューティング

• apt のインストール後に python3 -c "import holoscan" が失敗する。 想定どおりです。Debian パッケージには v3.0.0 以降、C++ のみが含まれています。Python バインディングを追加するには、/holoscan-install-wheel を実行してください。
• サンプルの実行時に「CUDA driver version is insufficient」と表示される。 パッケージの種類が間違っています。nvidia-smi の CUDA Version を再確認し、種類を切り替えてください：sudo apt-get remove -y holoscan-cuda-13 && sudo apt-get install -y holoscan-cuda-12（またはその逆）。
• E: Unable to locate package holoscan-cuda-12。 cuda-keyring がインストールされていないか、リポジトリがまだ取得されていません。ステップ 2 のキーリングと apt-get update のブロックを実行してください（ホストに合わせて ubuntu2204 / ubuntu2404 を調整してください）。
• サンプルの起動時にセグメンテーションフォルトが発生する。 現在のシェルで ulimit -s 32768 が設定されていません。ステップ 3 の形式に従い、コマンドの前に指定してください。
• error while loading shared libraries: libholoscan_core.so。 LD_LIBRARY_PATH が設定されていません。ステップ 4 の環境設定スニペットを使用してください：export LD_LIBRARY_PATH=/opt/nvidia/holoscan/lib。
• video_replayer がデータを見つけられない。 HOLOSCAN_INPUT_PATH=/opt/nvidia/holoscan/data を設定するか、sudo /opt/nvidia/holoscan/examples/download_example_data を実行して racerx データセットを取得してください。