holoscan-setup

Holoscan SDK のセットアップ

目的

ハードウェア、OS、CUDA ドライバー、既存のツールを調べて、現在のホストに適した Holoscan SDK のインストール方法を判断し、方法ごとのインストールスキルに引き継ぎます。Ubuntu、RHEL、IGX Orin、Jetson、DGX Spark／Grace-Hopper プラットフォームでの NGC コンテナ、Debian／apt、pip ホイール、Conda、ソースからのビルドに対応します。

前提条件

• Linux ホスト（Ubuntu 22.04/24.04、RHEL 9.x、IGX Orin、Jetson、または DGX Spark／Grace-Hopper）
• 動作するドライバーを備えた NVIDIA GPU（nvidia-smi が CUDA Version を返すこと）
• docs.nvidia.com と NGC へのネットワークアクセス
• 次のいずれか（選択した方法によります）：Docker と NVIDIA Container Toolkit、apt、pip を備えた Python 3.10–3.13、Conda、またはビルドツールチェーン

利用可能なスクリプト

スクリプト	目的	引数
scripts/check_conda.sh	PATH に含まれていない場合でも Conda のインストールを検出します（~/miniconda3、~/miniforge3、~/anaconda3、~/mambaforge、/opt/conda、シェルの rc ファイルを検索します）。環境と、holoscan をインポートできる環境を報告します。	なし
scripts/check_ngc_image.sh	指定された CUDA タグの接尾辞に対応する NGC Holoscan コンテナイメージがプル済みか、利用可能かを確認します。	<cuda-tag-suffix> — cuda13、cuda12-dgpu、cuda12-igpu のいずれか

run_script("scripts/check_conda.sh") および run_script("scripts/check_ngc_image.sh", "cuda13") でスクリプトを実行します。which conda や docker images のような単独のコマンドより、スクリプトの出力を優先してください。

手順

会話形式で段階的に進め、すべての情報を最初に提示しないでください。各ステップを完了して結果を報告してから、次に進みます。

ワークフロールール（必ず従うこと）

1. ステップ 5 の最後に、方法を明記した太字の一行の推奨を記載します（例：**Recommendation:** NGC Container — bundles all deps, fastest path to a working install.）。
2. サポート対象の x86_64 ホストで Docker を利用できる初回利用者には、NGC Container を推奨しなければなりません。
3. 推奨を提示した後は、どの方法を使うかユーザーに尋ねて停止します。そのターンでは docker pull、docker run、apt install、pip install、その他のインストールコマンドを記載しないでください。これらはステップ 6 で委譲するインストールスキルの担当です。
4. コンテナを使う場合は、ステップ 4 で Docker と GPU パススルーを自分で確認します（そこで示されているコマンドを実行してください）。ユーザーに代わって nvidia-smi や docker --version を実行するよう頼まないでください。

ステップ 1：まずドキュメントを読む

https://docs.nvidia.com/holoscan/sdk-user-guide/ を取得してから sdk_installation.html を取得し、現行リリースでサポートされているプラットフォーム、パッケージ名、インストール要件を確認します。ハードコードされた前提に頼らないでください。

ステップ 2：マシンを調べる

並列で実行します：

uname -a && (lsb_release -a 2>/dev/null || cat /etc/os-release)
uname -m
nvidia-smi 2>&1 | head -10
nproc && free -h | head -2

要点： nvidia-smi の「CUDA Version」フィールド（表のヘッダーの右上）を確認してください。これはドライバーがサポートする 最大 CUDA バージョンであり、cuda12 と cuda13 のどちらのパッケージを選ぶかを決めます。

ステップ 3：互換性を評価する

プラットフォーム	利用可能な方法
Ubuntu 22.04/24.04、x86_64	コンテナ、Debian／apt、pip ホイール、Conda、ソース
RHEL 9.x、x86_64	コンテナのみ
IGX Orin（ARM64）	コンテナ、Debian／apt、ソース
Jetson AGX Orin／Orin Nano	コンテナ、Debian／apt（iGPU）
Jetson AGX Thor	コンテナ、Debian／apt
DGX Spark／Grace-Hopper	コンテナ（OS 要件はドキュメントを確認）
その他の Linux、x86_64	コンテナが動作する場合があります。glibc ≥ 2.35 なら pip ホイールも利用できます

ステップ 4：ツールを確認し、選択肢を提示する

並行して実行します。

docker --version 2>&1 | head -1; python3 --version 2>&1; pip3 --version 2>&1
dpkg -l | grep holoscan || true
pip3 show holoscan 2>/dev/null | grep -E "^(Name|Version)" || true
~/holoscan/venv/bin/pip show holoscan 2>/dev/null | grep -E "^(Name|Version)" | sed 's/^/venv: /' || true

次に、GPU パススルーを自分で確認します。ユーザーには実行を依頼しないでください。

docker run --rm --gpus all ubuntu:22.04 nvidia-smi 2>&1 | tail -5 || true

ステップ 5 の Status 列には、結果を次のように記載します。

• docker が見つからない → コンテナ行の Status は ✗ — Docker not installed。
• Docker はあるが、could not select device driver "nvidia" と表示される → ✗ — NVIDIA Container Toolkit missing。
• nvidia-smi の出力が表示される → ✓。

続いて、run_script を使って検出スクリプトを実行します。

• run_script("scripts/check_conda.sh") — conda --version よりこちらが推奨される理由は、上記の利用可能なスクリプトを参照してください。
• run_script("scripts/check_ngc_image.sh", "<cuda-tag-suffix>") — <cuda-tag-suffix> をステップ 2 で判定したタグに置き換えます（例：cuda13、cuda12-dgpu、cuda12-igpu）。

Holoscan がすでにインストールされている場合は、バージョンを伝え、アップグレードするか、既存のインストールを確認するかを尋ねます。

CUDA バリアントのルール（正式な参照情報。以下のすべてのステップで適用します）。

nvidia-smi の CUDA Version	ネイティブパッケージ	コンテナタグ
13.x 以上	holoscan-cu13 / holoscan-cuda-13	cuda13
12.x、Blackwell GPU	holoscan-cu12 / holoscan-cuda-12	cuda13（Forward Compat）または cuda12-dgpu
12.x、Ampere/Ada dGPU	holoscan-cu12 / holoscan-cuda-12	cuda12-dgpu
ARM64 iGPU（Jetson、IGX）	holoscan	cuda12-igpu

ネイティブインストールでは、ドライバーの CUDA バージョンが上限となります。コンテナは Forward Compatibility に対応しています（「CUDA Forward Compatibility mode ENABLED」と表示されるのは想定どおりであり、エラーではありません）。

ステップ 5：選択肢を提示し、推奨する

表にはすべての方法を必ず含め、行を省略しないでください。Status 列にはホストで利用可能かどうかを記載します（利用できない方法には、短い理由を添えて ✗ を表示します）。表は次の形式にします。

方法	最適な用途	Status
NGC Container	すべての依存関係（CUDA、TensorRT、LibTorch、ONNX Runtime、Vulkan）を同梱。C++ と Python に対応。Docker と NVIDIA Container Toolkit が必要です。	Docker の有無に応じて ✓/✗
Debian/apt	Ubuntu ネイティブ環境。C++ のみ	パッケージがインストールされている場合は ✓/✗
pip wheel	Python のみのプロジェクト。CUDA Toolkit が PATH 上に必要です。Python 3.10～3.13 に対応。	~/holoscan/venv の仮想環境に wheel がインストールされている場合は ✓/✗
Conda	CUDA 13 のみ。すでに conda 環境にいる場合に適しています。	check_conda.sh の出力に応じて ✓/✗（which conda だけで判断しないでください）
Source	SDK 内部の変更、カスタム CMake フラグ、デバッグシンボル、未対応プラットフォーム、または未リリースのブランチ。	すでに ~/holoscan/holoscan-sdk にクローンされている場合は ✓/✗

表の後は、次の2行の形式で応答を終えます。

推奨： <method> — <理由を1行で>

どの方法を使用しますか？（container / apt / wheel / conda / source）

ユーザーが Holoscan を初めて使用し、ホストが対応する x86_64 プラットフォームで Docker が利用可能な場合は、NGC Containerを推奨します。RHEL 9 またはコンテナのみを利用できるホストでは、コンテナを推奨します。Docker を利用できないホストで Python のみのプロジェクトを行う場合は、pip wheel を推奨します。

このターンでは docker pull、docker run、apt install、pip install コマンドを含めないでください。これらはステップ 6 で呼び出すインストールスキルで扱います。表の途中で応答が切れないよう、回答は短くしてください。

ステップ 6：インストールスキルに委任する

方法を選んだら、対応するスキルを呼び出します。インストール手順をその場で繰り返さないでください。

方法	呼び出すスキル
NGC コンテナ	/holoscan-install-container
Debian/apt	/holoscan-install-debian
pip ホイール	/holoscan-install-wheel
Conda	/holoscan-install-conda
ソース	/holoscan-install-source

スキルを呼び出す際は、CUDA の種類（cu12/cu13/igpu）と、ステップ 2～4 で得られたその他の関連情報をコンテキストとして渡してください。

インストールスキルが、推奨されるコンテナーフラグ（--gpus all、--ipc=host、--ulimit memlock=-1、--ulimit stack=67108864、コンテナー内の ulimit -s 32768）や検証例を含む、すべてのコマンドを担当します。holoscan-setup からこれらを再掲せず、委任してインストールスキルに提示させてください。

ステップ 7：概要

インストールが成功し、テストを実行した場合は、テスト結果の概要を表にして出力してください。

制限事項

• RHEL 9.x で対応しているのは NGC コンテナ方式のみです。ネイティブパッケージは公開されていません。
• Conda パッケージは CUDA 13 のみです。CUDA 12 のホストでは、コンテナー、apt、pip ホイール、またはソースを使用してください。
• Debian/apt でインストールされるのは Holoscan v3.0.0 以降、C++ のみです。Python のサポートには、追加で pip ホイールをインストールする必要があります。
• pip ホイールには、glibc ≥ 2.35 および Python 3.10–3.13 が必要です。
• ネイティブインストールでは、ドライバーが報告する CUDA Version を超えることはできません。CUDA Forward Compatibility を使用できるのはコンテナーのみです。
• DGX Spark / Grace-Hopper の OS 要件はリリースによって変わります。必ず sdk_installation.html を再確認してください。

トラブルシューティング

• conda --version で「command not found」と表示されるが、Conda はインストール済み — zsh の遅延読み込みされた Conda や、.bashrc の実行時にのみ conda init が実行された環境でよく発生します。run_script("scripts/check_conda.sh") を使用してください。インストールディレクトリと rc ファイルを検索します。
• nvidia-smi に予想より低い CUDA Version が表示される — この項目はドライバーがサポートする CUDA の最大バージョンであり、インストール済みのツールキットのバージョンではありません。より新しい CUDA のパッケージをインストールする前に、ドライバーをアップグレードしてください。
• Debian のインストールは成功するが、Python で import holoscan に失敗する — v3.0.0 以降、apt でインストールされるのは C++ のみです。続けて /holoscan-install-wheel を実行してください。
• pip install holoscan が glibc エラーで失敗する — ホストの glibc が 2.35 未満です。代わりにコンテナーまたは apt を使用してください。
• check_ngc_image.sh でイメージが見つからないと報告される — NGC へのログイン（docker login nvcr.io）と、タグのサフィックスがステップ 4 の CUDA の種類に関するルールに一致していることを確認してください。