cupynumeric-install

cuPyNumeric 安装（用户）

目的

使用此技能安装 cuPyNumeric，以便在 Python 中使用，并验证安装确实有效（包括 GPU 使用情况）。只要用户希望通过 conda 或 pip 运行 cuPyNumeric，就应用此技能。请勿用它从源代码构建（用于修改或贡献）；这不在范围内。

强制规则

• 绝不运行安装操作。 不要运行 pip install、conda install 或任何安装程序。请输出命令，让用户自行运行。
• 始终隔离。 不要安装到 base conda、系统 Python 或共享全局环境中。
• 建议前先检测。 可以进行只读的 --version 检查。

先决条件

推荐任何安装方式之前，请确认以下系统要求：

• GPU：计算能力 ≥ 7.0（Volta 及更高版本）。也支持仅使用 CPU。
• CUDA：12.2 及更高版本。
• 操作系统：Linux（x86_64 / aarch64）、macOS aarch64（仅 pip 轮子包）、Windows（通过 WSL）。
• 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 的笔记本电脑、云端、容器，还是远程/服务器。
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

通过操作系统的包管理器（apt/dnf/brew）或 https://www.python.org/downloads/ 安装 Python。如果现有 Python 缺少 pip：python -m ensurepip --upgrade。

安装后，打开一个新的 shell，以便二进制文件加入 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 变体也能得到正确结果。请运行以下两个步骤。

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 已被调用。 在同一个 shell 中运行带截止时间限制的矩阵乘法循环，同时运行 nvidia-smi——避免在第二个终端中运行造成竞争：

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 中是否为 *_gpu（而非 *_cpu）。

更深入的操作指南

多 GPU 检查、CPU 回退、容器和故障排除，请参阅 verification_examples.md。

限制

• 不要在同一环境中混用 conda 和 pip。 混用会覆盖首次安装的内容，并导致导入失败。要切换时，请先运行 pip uninstall nvidia-cupynumeric 或 conda remove cupynumeric。
• 多 GPU / 多 rank 运行时，请使用 legate 启动器。 直接使用 python 只会运行单进程：legate --gpus 2 script.py。
• 仅在 CPU 主机上使用 CONDA_OVERRIDE_CUDA 强制安装 GPU 变体。 否则，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' → 在同一个 shell 中运行 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 进行确认。
• 在笔记本电脑上比 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