cupynumeric-install

cuPyNumeric のインストール（ユーザー向け）

目的

このスキルは、Python で 使用するために cuPyNumeric をインストールし、インストールが実際に機能すること（GPU の使用を含む）を確認する際に使用します。ユーザーが conda または pip で cuPyNumeric を使えるようにしたい場合に適用します。ソースからのビルド（変更やコントリビューションのため）には使用しないでください。それは対象外です。

必須ルール

• インストールは絶対に実行しないでください。 pip install、conda install、その他のインストーラーを実行しないでください。コマンドを表示し、ユーザー自身に実行してもらいます。
• 必ず環境を分離してください。 base conda、システムの Python、共有のグローバル環境にはインストールしないでください。
• 推奨する前に検出してください。 読み取り専用の --version チェックは問題ありません。

前提条件

インストールを推奨する前に、次のシステム要件を確認してください。

• GPU：Compute Capability ≥ 7.0（Volta 以降）。CPU のみの環境にも対応しています。
• CUDA：12.2 以降。
• OS：Linux（x86_64 / aarch64）、macOS aarch64（pip ホイールのみ）、WSL 経由の Windows。
• Python：Linux では 3.11～3.14、macOS aarch64 では 3.11～3.13。
• conda：24.1 以降（conda の場合のみ）。
• パッケージマネージャー：conda（上流が推奨）または pip。どちらもない場合は、先にセットアップしてください（手順を参照）。

手順

次の手順を順番に実行します。前提条件を確認し、環境の確認事項を質問してから、選択した方法でインストールし、最後に検証します。

インストール前に確認する

1. パッケージマネージャーはありますか？ conda --version と pip --version を確認します。conda（上流が推奨）を優先し、使用できない場合は pip を使います。
2. 対象環境はどれですか？ GPU マシン、CPU のみのノート PC、クラウド、コンテナー、リモート環境／サーバー。
3. CUDA のバージョンは？ GPU が認識されないホストで GPU 版を強制する場合にのみ確認します。nvidia-smi ／ nvcc --version で確認してください。

セットアップ — 先にパッケージマネージャーをインストールする

conda と pip のどちらも使えない場合は、いずれかをインストールします。コマンドとドキュメントへのリンクを提示してください。実行してはいけません — curl | bash の実行にはユーザーの信頼が必要です。

推奨：Miniforge（conda 一式、デフォルトは conda-forge）

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash "Miniforge3-$(uname)-$(uname -m).sh"

ドキュメント：https://github.com/conda-forge/miniforge

代替：Python + pip

OS のパッケージマネージャー（apt/dnf/brew）または https://www.python.org/downloads/ から Python をインストールしてください。既存の Python に pip がない場合は、python -m ensurepip --upgrade を実行します。

インストール後、バイナリが PATH に反映されるよう、新しいシェルを開いてください。

インストール — conda を使う場合

conda create -n cupynumeric -c conda-forge -c legate cupynumeric
conda activate cupynumeric

既存の環境にインストールする場合：conda install -c conda-forge -c legate cupynumeric。

conda は、インストール時に nvidia-smi が動作するかどうかに基づいて、GPU 版と CPU 版を自動選択します。これを上書きする方法は、以下を参照してください。

GPU 版を強制する

インストール時に GPU が認識されない場合（GPU ホスト向けのコンテナーをビルドする場合など）にのみ、CONDA_OVERRIDE_CUDA を設定してください。実行ホストの CUDA バージョンを使用します。

CONDA_OVERRIDE_CUDA="12.2" conda install -c conda-forge -c legate cupynumeric

Nightly（検証が少ないバージョン）

conda install -c conda-forge -c legate-nightly cupynumeric

インストール — pip を使う場合

python -m venv .venv
source .venv/bin/activate
pip install nvidia-cupynumeric

検証

スモークテスト（必ず実行）

リポジトリをチェックアウトせずに実行できる、自己完結型のスクリプトを legate ランチャー経由で実行します。

TMP=$(mktemp -d)
cat > "$TMP/smoke.py" <<'EOF'
import cupynumeric as np
a = np.arange(10)
b = np.ones((4, 4))
print("sum:", a.sum())            # expect 45
print("matmul:", (b @ b).sum())   # expect 64.0
EOF
legate "$TMP/smoke.py"
rm -rf "$TMP"

sum: 45 と matmul: 64.0 が出力されることを確認してください。legate が見つからない場合、環境が有効化されていません。トラブルシューティングを参照してください。

GPU 使用状況の確認（対応 GPU がある場合は必須）

スモークテストに合格しても、GPU が使用された証明にはなりません。GPU 搭載マシンでも、CPU 版をインストールすれば正しい結果が出ます。次の 2 つの手順を両方実行してください。

1. GPU を強制的に使用して起動する。 legate --gpus N は N 個の GPU を要求します。GPU が認識されない場合や CPU 版がインストールされている場合は、すぐに失敗します。

TMP=$(mktemp -d)
cat > "$TMP/check.py" <<'EOF'
import cupynumeric as np
print(np.ones((4096, 4096)).sum())
EOF
legate --gpus 1 "$TMP/check.py"
rm -rf "$TMP"

16777216.0 が出力されることを確認してください。CUDA driver、libcudart、または no GPUs available が表示された場合は、CPU 版がインストールされています。CONDA_OVERRIDE_CUDA を指定して再インストールしてください。

2. GPU が実際に使用されたことを確認する。 デッドラインを設定した matmul ループと nvidia-smi を、2 つ目のターミナルとの競合が起きないよう、1 つのシェルから実行します。

TMPDIR_GPU=$(mktemp -d)
SCRIPT="$TMPDIR_GPU/cupynumeric_gpu_check.py"
cat > "$SCRIPT" <<'EOF'
import cupynumeric as np, time
a = np.ones((10000, 10000))
deadline = time.time() + 20
iters = 0
while time.time() < deadline:
    b = a @ a
    _ = float(b.sum())   # force sync so the matmul actually runs
    iters += 1
print("iters:", iters)
EOF
legate --gpus 1 "$SCRIPT" &
WORKLOAD=$!
sleep 5                                     # buffer for Legate startup
for _ in $(seq 10); do                      # 10 samples at 1s — covers slow startup
  nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
  sleep 1
done
wait "$WORKLOAD"
rm -rf "$TMPDIR_GPU"

ほとんどのサンプルで memory.used が GiB 単位になり、複数のサンプルで utilization.gpu がゼロではない値になることを確認してください。すべてのサンプルで両方がベースラインのままの場合、GPU 版はインストールされていません。conda list cupynumeric を実行し、*_cpu ではなく *_gpu になっているか確認してください。

より詳しいレシピ

マルチ GPU の確認、CPU へのフォールバック、コンテナ、トラブルシューティングについては、verification_examples.md をご覧ください。

制限事項

• 1 つの環境で conda と pip を併用しないでください。 併用すると、先にインストールしたものが上書きされ、インポート時に問題が発生します。切り替えるには、先に pip uninstall nvidia-cupynumeric または conda remove cupynumeric を実行してください。
• マルチ GPU／マルチランクの実行には legate ランチャーを使用してください。 通常の python では単一プロセスで実行されます：legate --gpus 2 script.py。
• CPU のみのホストで GPU 版を強制するには CONDA_OVERRIDE_CUDA を使用してください。 指定しない場合、conda はインストール時に nvidia-smi をもとに CPU 版または GPU 版を自動選択します。
• Volta 以降が必要です。 Pascal（GTX 10xx／P100）はサポートされていません。
• conda --version が ≥ 24.1 であることを確認してください。 古いリリースでは、バリアントの選択が通知なく失敗します。
• マルチノード／MPI／UCX は対象外です。 https://docs.nvidia.com/legate/latest/networking-wheels.html および https://docs.nvidia.com/legate/latest/mpi-wrapper.html を参照してください。

トラブルシューティング

• ModuleNotFoundError: No module named 'cupynumeric' → 同じシェルで which python と pip list | grep cupynumeric（または conda list | grep cupynumeric）を実行して、環境の不一致を確認してください。
• CUDA／libcudart に言及する ImportError → CONDA_OVERRIDE_CUDA="<your-cuda-version>" を指定して再インストールしてください。GPU マシンに CPU 版がインストールされているか、CUDA のバージョンが一致していません。
• legate: command not found → 環境を有効化してから、which legate を実行して確認してください。
• ノート PC で NumPy より遅い → 小規模な問題では想定される動作です（Legate のタスクごとのオーバーヘッド）。cuPyNumeric の FAQ をご覧ください。

関連項目

• references/verification_examples.md — 確認およびトラブルシューティングのレシピ。
• 上流のドキュメント：https://docs.nvidia.com/cupynumeric/latest/installation.html
• Legate の要件：https://docs.nvidia.com/legate/latest/installation.html