
名称	cupynumeric-install
描述	为 Python 安装并验证 cuPyNumeric——环境要求、命令、验证。源代码构建不在范围之内。
开源协议	CC-BY-4.0 OR Apache-2.0 compatibility: linux-x86_64, linux-aarch64, wsl-x86_64 metadata:
作者	“NVIDIA Corporation legate@nvidia.com”
版本	“2.0.0” tags: - cupynumeric - legate - numpy - installation - conda - gpu - distributed-computing upstream: https://github.com/nv-legate/cupynumeric docs: https://docs.nvidia.com/cupynumeric/latest/installation.html

cuPyNumeric 安装（用户）

用途

使用本技能从 Python 安装 cuPyNumeric 以供使用，并验证安装是否真的有效（包括 GPU 使用）。只要用户想要通过 conda 或 pip 运行 cuPyNumeric，就应用此技能。请勿用于从源码构建（修改或贡献）——这不在范围内。

强制规则

绝不运行安装。 不要运行 pip install、conda install 或任何安装程序。打印命令，让用户自行运行。
始终隔离环境。 不要安装到基础 conda、系统 Python 或共享的全局环境中。
推荐前先检测。 只读的 --version 检查没有问题。

先决条件

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

GPU：计算能力 ≥ 7.0（Volta+）。也支持仅 CPU。
CUDA：12.2+。
操作系统：Linux（x86_64 / aarch64），Windows 通过 WSL。
Python：3.11 至 3.14
conda：≥ 24.1（仅 conda 路径）。
包管理器：conda（上游推荐）或 pip。如果两者都不存在，请先启动一个（参见“说明”）。

说明

按顺序执行以下步骤：确认先决条件、询问范围问题、通过所选路径安装，然后验证。

安装前询问

包管理器？ 检查 conda --version 和 pip --version。首选 conda（上游推荐）；否则回退到 pip。
环境目标？ GPU 机器、仅 CPU 的笔记本电脑、云、容器或远程/服务器。
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 的情况下设置 CONDA_OVERRIDE_CUDA（例如为 GPU 主机构建容器时）。使用运行时主机的 CUDA 版本：

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

每晚构建（验证较少）

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）。

限制

不要在一个环境中混用 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），以找出环境不匹配。
ImportError 提及 CUDA / libcudart → 使用 CONDA_OVERRIDE_CUDA="<your-cuda-version>" 重新安装；CPU 变体装在 GPU 机器上，或 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

cuPyNumeric安装Skill cupynumeric-install