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）、WSL 経由の Windows。
• Python：3.11～3.14
• 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 も利用できない場合は、いずれかをインストールします。コマンドとドキュメントへのリンクを提示してください。実行してはいけません。

推奨：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 版を強制する

CONDA_OVERRIDE_CUDA は、インストール時に GPU が確認できない場合（例：GPU ホスト向けにコンテナーをビルドする場合）にのみ設定してください。実行ホストの 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 版をインストールした場合でも、正しい結果が得られます。両方の手順を実行してください。

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 が使用されたことを確認する。 2 つ目のターミナルとの競合を避けるため、期限付きの行列乗算ループと nvidia-smi を、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 を参照してください。

制限事項

• 同じ環境で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