holoscan-install-conda

Holoscan Conda のインストール

目的

Linux x86_64 の Conda 環境に、正しく固定した CUDA メタパッケージを使用して、Holoscan SDK（Python ランタイムおよび／または C++ 開発ヘッダー）を conda-forge と rapidsai からインストールします。

前提条件

• NVIDIA GPU と CUDA 13 ドライバーを搭載した Linux x86_64（nvidia-smi で確認してください）。
• conda（Miniforge を推奨）。見つからない場合はステップ 1 でインストールします。
• conda-forge、rapidsai、docs.nvidia.com へのネットワークアクセス。

制限事項

• CUDA 13 のみ（v4.3.0 以降。以前のリリースは CUDA 12 でした）。CUDA 12 ドライバーを使用している場合は、代わりに /holoscan-install-container または /holoscan-install-wheel を案内してください。
• Linux x86_64 のみ — conda-forge では aarch64／iGPU をサポートしていません。
• Holoscan を実行する各シェルで ulimit -s 32768 を設定することを推奨します。設定しないと、一部のアプリがセグフォールトを起こす可能性があります。

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

インストール前に、必ず https://docs.nvidia.com/holoscan/sdk-user-guide/sdk_installation.html の最新の Conda セクションを取得してください。パッケージ名、チャンネルの選択、ランタイムと開発用パッケージの分割は、リリースによって変更される場合があります。具体的には、以下を確認してください。

• 正確なランタイムパッケージ名（例：Python バインディング用の holoscan）。
• C++ 開発用パッケージの名前と、それが必要かどうか。v4.1.0 以降、ヘッダーと CMake 設定を含む libholoscan-dev は独立したパッケージです。C++ アプリを開発する場合は必ずインストールしてください。インストールしないと find_package(holoscan) が失敗し、#include するヘッダーもありません。
• 現行リリースでサポートされている Python のバージョン（v4.3 では 3.10～3.13）。
• 現在の cuda-version の固定値（v4.3 → 13）。

rmm と ucxx は rapidsai チャンネルから配布されます。holoscan、libholoscan、libholoscan-dev は conda-forge から提供されます。

ドキュメントの内容が以下と異なる場合は、ドキュメントを優先してください。インストールコマンドをそれに合わせて更新し、ユーザーに伝えてください。

ステップ 1：前提条件を確認する

conda --version 2>&1
nvidia-smi 2>&1 | head -5

conda が見つからない場合は、Miniforge をサイレントインストールします（conda-forge では Miniconda より Miniforge を推奨します）。

wget -q https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O /tmp/Miniforge3.sh
bash /tmp/Miniforge3.sh -b -p ~/miniforge3
source ~/miniforge3/etc/profile.d/conda.sh
conda --version

-b フラグを指定すると、.bashrc を変更せずに非対話形式でインストールされます。conda を使用できるようにするには、新しいシェルを開くたびに source ~/miniforge3/etc/profile.d/conda.sh を実行するか、シェルの RC ファイルに追加する必要があります。

ステップ 2：環境を作成してインストールする

パッケージの役割

• libholoscan — C++ ランタイムシンボル（libholoscan_core.so）。依存関係として自動的にインストールされます。
• holoscan — Python バインディング。
• libholoscan-dev — C++ ヘッダー、libholoscan_core.so のシンボリックリンク、find_package(holoscan) 用の holoscan-config.cmake。
• rmm — RAPIDS Memory Manager（rapidsai チャンネル）。holoscan が宣言していないランタイム依存関係です。これがないと import holoscan は失敗します。
• ucxx — UCX Python バインディング（rapidsai チャンネル）。分散アプリ／マルチプロセスアプリに必要です。
• cuda-version=13 — CUDA 13 メタパッケージを固定し、互換性のある CUDA ランタイムライブラリをソルバーが選択できるようにします。

まず環境を作成します。

source ~/miniforge3/etc/profile.d/conda.sh   # if conda not yet on PATH
conda create -n holoscan python=3.13 -y
conda activate holoscan

次に、ユーザーの目的に応じて以下のバリエーションから 1 つを選択してください。

ユーザーの目的に合わせてパッケージを選択します。Python のみの場合は holoscan、C++ 開発の場合は libholoscan-dev、両方を使用する場合はどちらも必要です。

conda install <packages> rmm ucxx cuda-version=13 -c rapidsai -c conda-forge -y

C++ 開発では、ツールチェーンもインストールしてください。

conda install -c conda-forge cxx-compiler cmake ninja -y

Python のインストールは python3 -c "import holoscan; print(holoscan.__version__)" で確認してください。C++ 開発用のインストールは ls "$CONDA_PREFIX/include/holoscan" で確認してください。

ステップ 3：Python テストを実行する

ulimit -s 32768 を推奨します。これを設定しないと、一部の Holoscan アプリが起動時にセグメンテーションフォールトを起こすことがあります。

video_replayer は、デフォルトで無限にループするディスプレイアプリです。必ず YAML を変更して、10 フレーム後に停止するようにし（count: 10、repeat: false、realtime: false）、ヘッドレスで実行するようにしてください（headless: true）。ヘッドレスはディスプレイの有無にかかわらず動作し、SSH 接続時の GUI 関連のエラーを避けられるため、$DISPLAY に応じて処理を分岐する必要はありません。

スクリプトと YAML 設定ファイルをダウンロードし、YAML を変更してから実行します。

source ~/miniforge3/etc/profile.d/conda.sh
conda activate holoscan
ulimit -s 32768

SDK_VER=$(python3 -c "import holoscan; print(holoscan.__version__)")
BASE="https://raw.githubusercontent.com/nvidia-holoscan/holoscan-sdk/v${SDK_VER}/examples"

curl -fsSL "${BASE}/hello_world/python/hello_world.py"         -o /tmp/hs_hello_world.py
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/video_replayer.yaml

# Patch video_replayer.yaml — 10 frames, headless.
python3 -c "
c = open('/tmp/video_replayer.yaml').read()
c = c.replace('count: 0', 'count: 10')
c = c.replace('repeat: true', 'repeat: false')
c = c.replace('realtime: true', 'realtime: false')
c = c.replace('  width: 854', '  headless: true\n  width: 854')
open('/tmp/video_replayer.yaml', 'w').write(c)"

# hello_world — no display, no data needed; expected: "Hello World!"
python3 /tmp/hs_hello_world.py

# video_replayer — needs racerx data; expected: frames rendered, "Graph execution finished."
HOLOSCAN_INPUT_PATH=/path/to/holoscan/data python3 /tmp/hs_video_replayer.py

HOLOSCAN_INPUT_PATH は、racerx/ サブディレクトリを含むディレクトリを指している必要があります。 ユーザーが SDK ソースリポジトリを持っている場合は、~/repos/holoscan-sdk/data が該当します。それ以外の場合は、Debian またはソースインストールツリーにある download_ngc_data スクリプトでダウンロードしてください。

ステップ 4：ユーザーに案内する

新しいシェルセッションを開始するたびに、以下を実行する必要があります。

source ~/miniforge3/etc/profile.d/conda.sh   # if Miniforge was installed with -b
conda activate holoscan
ulimit -s 32768   # recommended — prevents segfaults in some apps

繰り返し実行しなくて済むよう、これらの行を ~/.bashrc または ~/.zshrc に追加することを検討してください。

次のステップとして、以下を案内します。

• C++ と Python のサンプルを確認する：https://github.com/nvidia-holoscan/holoscan-sdk/tree/v<VERSION>/examples
• 特定のサンプルを順を追って確認する：/explain-example
• カスタム Holoscan アプリケーションの構築を開始する

トラブルシューティング

• ImportError: librmm.so: cannot open shared object file。 rmm がインストールされていません。ステップ 2 の conda install 行を再実行してください。rmm は holoscan の未宣言のランタイム依存関係です。
• ソルバーが予想より古い holoscan ビルドを選択する。 チャネルの順序が間違っている可能性があります。-c rapidsai -c conda-forge を使用してください（rapidsai を先にします）。これは公式インストールコマンドの順序であり、厳格なチャネル優先度の下では、conda-forge を先にするとソルバーが古い holoscan ビルドに固定されることがあります。
• アプリの起動時にセグメンテーションフォールトが発生する。 Holoscan アプリを実行する前に、現在のシェルで ulimit -s 32768 を設定してください。すべてのアプリで発生するわけではありませんが、スタックを大きくすることでこの問題を回避できます。
• C++ アプリのビルド時に find_package(holoscan) が失敗する。 libholoscan-dev をインストールしてください（v4.1.0 以降、ヘッダーと CMake 設定ファイルは別パッケージに含まれています）。
• 新しいシェルで conda: command not found が表示される。 Miniforge は -b を指定してインストールされたため、.bashrc は変更されていません。source ~/miniforge3/etc/profile.d/conda.sh を実行するか、シェルの RC ファイルに追加してください。