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）、通过 WSL 使用 Windows。
• Python：3.11 至 3.14
• 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 都不可用，请先安装其中一个。提供命令和文档链接；不要运行命令。

推荐：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 常见问题。

另请参阅

• references/verification_examples.md — 验证和故障排除示例。
• 上游文档：https://docs.nvidia.com/cupynumeric/latest/installation.html
• Legate 要求：https://docs.nvidia.com/legate/latest/installation.html