安装#

要求#

  • NVIDIA CUDA GPU，计算能力 3.0 或更高。

  • CUDA Toolkit: v11.2 / v11.3 / v11.4 / v11.5 / v11.6 / v11.7 / v11.8 / v12.0 / v12.1 / v12.2 / v12.3 / v12.4 / v12.5 / v12.6 / v12.8

    • 如果您安装了多个版本的 CUDA Toolkit，CuPy 将自动选择其中一个 CUDA 安装。有关详细信息，请参阅使用自定义 CUDA 安装。

    • 如果您从 conda-forge 安装 CuPy，则此要求是可选的。但是，您的 GPU 仍然需要安装兼容的驱动程序。有关详细信息，请参阅从 Conda-Forge 安装 CuPy。

  • Python: v3.9 / v3.10 / v3.11 / v3.12 / v3.13

注意

目前，CuPy 已在 Ubuntu 20.04 LTS / 22.04 LTS (x86_64)、CentOS 7 / 8 (x86_64) 和 Windows Server 2016 (x86_64) 上进行了测试。

Python 依赖项#

CuPy v13 中与 NumPy/SciPy 兼容的 API 基于 NumPy 1.26 和 SciPy 1.11，并已针对以下版本进行了测试

注意

SciPy 和 Optuna 是可选依赖项，不会自动安装。

注意

在安装 CuPy 之前，我们建议您升级 setuptools 和 pip

$ python -m pip install -U setuptools pip

附加 CUDA 库#

CuPy 中的部分 CUDA 功能仅在安装了相应的库后才能激活。

  • cuTENSOR: v2.0

    • 用于加速张量操作的库。有关详细信息，请参阅环境变量。

  • NCCL: v2.16 / v2.17 / v2.18 / v2.19 / v2.20 / v2.21 / v2.22 / v2.25

    • 用于执行集合式多 GPU / 多节点计算的库。

  • cuDNN: v8.8

    • 用于加速深度神经网络计算的库。

  • cuSPARSELt: v0.2.0

    • 用于加速稀疏矩阵乘法的库。

安装 CuPy#

从 PyPI 安装 CuPy#

Linux 和 Windows 提供 wheels（预编译二进制包）。包名称因您的 CUDA Toolkit 版本而异。

CUDA

命令

v11.2 ~ 11.8 (x86_64 / aarch64)

pip install cupy-cuda11x

v12.x (x86_64 / aarch64)

pip install cupy-cuda12x

注意

要启用附加 CUDA 库（cuTENSOR / NCCL / cuDNN）提供的功能，您需要手动安装它们。如果您通过 wheels 安装了 CuPy，如果您之前没有安装，可以使用下面的安装程序命令来设置这些库

$ python -m cupyx.tools.install_library --cuda 11.x --library cutensor

注意

附加选项 --pre -U -f https://pip.cupy.dev/pre 来安装预发布版本（例如，pip install cupy-cuda11x --pre -U -f https://pip.cupy.dev/pre）。

使用 wheels 时，请注意不要同时安装多个 CuPy 包。这些包中的任何一个与 cupy 包（源码安装）会相互冲突。请确保只安装了一个 CuPy 包（cupy 或 cupy-cudaXX，其中 XX 是 CUDA 版本号）

$ pip freeze | grep cupy

从 Conda-Forge 安装 CuPy#

Conda 是一种跨语言、跨平台的包管理解决方案，广泛应用于科学计算和其他领域。上述 pip install 指令与 conda 环境兼容。另外，对于 Linux (x86_64, ppc64le, aarch64-sbsa) 和 Windows，一旦 CUDA 驱动程序正确设置，您也可以从 conda-forge 频道安装 CuPy

$ conda install -c conda-forge cupy

并且 conda 将为您安装一个预构建的 CuPy 二进制包，以及 CUDA 运行时库（CUDA 11 及以下版本使用 cudatoolkit，CUDA 12 及以上版本使用 cuda-XXXXX）。事先安装 CUDA Toolkit 不是必需的。

如果您的目标是最小化安装占用空间，您可以安装 cupy-core 包

$ conda install -c conda-forge cupy-core

它仅依赖于 numpy。通过这种方式不会安装任何 CUDA 库，您需要自行安装所需的依赖项，可以从 conda-forge 或其他地方获取。这相当于 cupy-cudaXX wheel 安装。

Conda 有内置机制来确定并安装您的驱动程序支持的最新版本 cudatoolkit 或任何其他 CUDA 组件。但是，如果出于任何原因您需要强制安装特定 CUDA 版本（例如 11.8），您可以执行

$ conda install -c conda-forge cupy cuda-version=11.8

注意

cuDNN、cuTENSOR 和 NCCL 在 conda-forge 上作为可选依赖项提供。以下命令可以一次性安装所有这些库

$ conda install -c conda-forge cupy cudnn cutensor nccl

每个库也可以根据需要单独安装。

注意

如果您在使用从 conda-forge 安装的 CuPy 时遇到任何问题，请随时向 cupy-feedstock 报告，我们将协助调查是 conda-forge 配方中的打包问题还是 CuPy 的实际问题。

注意

如果您没有自行安装 CUDA Toolkit，对于 CUDA 11 及以下版本，nvcc 编译器可能不可用，因为来自 conda-forge 的 cudatoolkit 包不包含 nvcc 编译器工具链。如果您想使用本地 CUDA 安装中的 nvcc，需要确保 CUDA Toolkit 的版本与 cudatoolkit 的版本匹配，以避免意外。对于 CUDA 12 及以上版本，可以通过以下方式在每个 conda 环境中安装 nvcc

$ conda install -c conda-forge cuda-nvcc

从源码安装 CuPy#

建议尽可能使用 wheel 包。但是，如果 wheel 无法满足您的要求（例如，您正在运行非 Linux 环境，或者想使用 wheel 不支持的 CUDA / cuDNN / NCCL 版本），您也可以从源码构建 CuPy。

注意

CuPy 源码构建需要 g++-6 或更高版本。对于 Ubuntu 18.04，运行 apt-get install g++。对于 Ubuntu 16.04、CentOS 6 或 7，请按照此处的说明进行操作。

注意

从源码安装 CuPy 时，如果附加 CUDA 库在构建时不可用，它们提供的功能将被禁用。有关说明，请参阅安装 cuDNN 和 NCCL。

注意

如果您升级或降级 CUDA Toolkit、cuDNN、NCCL 或 cuTENSOR 的版本，您可能需要重新安装 CuPy。有关详细信息，请参阅重新安装 CuPy。

您可以通过 pip 安装CuPy 源码包的最新稳定发布版本。

$ pip install cupy

如果您想从克隆的 Git 仓库安装 CuPy 的最新开发版本

$ git clone --recursive https://github.com/cupy/cupy.git
$ cd cupy
$ pip install .

注意

从源码构建 CuPy 需要 Cython 0.29.22 或更高版本。如果不可用，它将在构建过程中自动安装。

卸载 CuPy#

使用 pip 卸载 CuPy

$ pip uninstall cupy

注意

如果您使用的是 wheel，cupy 应替换为 cupy-cudaXX（其中 XX 是 CUDA 版本号）。

注意

如果 CuPy 是通过 conda 安装的，请改为执行 conda uninstall cupy。

升级 CuPy#

只需使用 pip install 并附加 -U 选项

$ pip install -U cupy

注意

如果您使用的是 wheel，cupy 应替换为 cupy-cudaXX（其中 XX 是 CUDA 版本号）。

重新安装 CuPy#

要重新安装 CuPy，请先卸载 CuPy，然后重新安装。重新安装 CuPy 时，我们建议使用 --no-cache-dir 选项，因为 pip 会缓存之前构建的二进制文件

$ pip uninstall cupy
$ pip install cupy --no-cache-dir

注意

如果您使用的是 wheel，cupy 应替换为 cupy-cudaXX（其中 XX 是 CUDA 版本号）。

在 Docker 中使用 CuPy#

我们提供官方 Docker 镜像。使用 NVIDIA Container Toolkit 运行带 GPU 的 CuPy 镜像。您可以使用 bash 登录环境，并运行 Python 解释器

$ docker run --gpus all -it cupy/cupy /bin/bash

或直接运行解释器

$ docker run --gpus all -it cupy/cupy /usr/bin/python3

常见问题#

pip 安装 CuPy 失败#

请确保您使用的是最新的 setuptools 和 pip

$ pip install -U setuptools pip

在 pip 命令中使用 -vvvv 选项。这将显示所有安装日志

$ pip install cupy -vvvv

如果您使用 sudo 安装 CuPy，请注意 sudo 命令不会传播环境变量。如果您需要传递环境变量（例如 CUDA_PATH），您需要在 sudo 命令中指定它们，如下所示

$ sudo CUDA_PATH=/opt/nvidia/cuda pip install cupy

如果您使用的是某些版本的 conda，可能会出现错误 g++: error: unrecognized command line option ‘-R’，导致无法构建 CuPy。这是由于 conda 中的一个错误（详情请参阅 conda/conda#6030）。如果您遇到此问题，请升级您的 conda。

安装 cuDNN 和 NCCL#

我们建议使用 NVIDIA 提供的二进制包（即使用 apt 或 yum）安装 cuDNN 和 NCCL。

如果您想安装 cuDNN 和 NCCL 的 tar-gz 版本，建议将其安装在 CUDA_PATH 目录下。例如，如果您使用 Ubuntu，将 *.h 文件复制到 include 目录，将 *.so* 文件复制到 lib64 目录

$ cp /path/to/cudnn.h $CUDA_PATH/include
$ cp /path/to/libcudnn.so* $CUDA_PATH/lib64

目标目录取决于您的环境。

如果您想使用安装在其他目录下的 cuDNN 或 NCCL，请在安装 CuPy 之前使用 CFLAGS、LDFLAGS 和 LD_LIBRARY_PATH 环境变量

$ export CFLAGS=-I/path/to/cudnn/include
$ export LDFLAGS=-L/path/to/cudnn/lib
$ export LD_LIBRARY_PATH=/path/to/cudnn/lib:$LD_LIBRARY_PATH

使用自定义 CUDA 安装#

如果您将 CUDA 安装在非默认目录，或者在同一主机上安装了多个 CUDA 版本，您可能需要手动指定 CuPy 应使用的 CUDA 安装目录。

CuPy 按以下顺序查找并使用找到的第一个 CUDA 安装目录。

  1. CUDA_PATH 环境变量。

  2. nvcc 命令的父目录。CuPy 从 PATH 环境变量中查找 nvcc 命令。

  3. /usr/local/cuda

例如，您可以通过 CUDA_PATH 环境变量使用非默认的 CUDA 目录构建 CuPy

$ CUDA_PATH=/opt/nvidia/cuda pip install cupy

注意

CUDA 安装发现也在运行时使用上述规则进行。根据您的系统配置，您可能还需要在运行时将 LD_LIBRARY_PATH 环境变量设置为 $CUDA_PATH/lib64。

CuPy 总是引发 NVRTC_ERROR_COMPILATION (6)#

在 CUDA 12.2 或更高版本上，编译 CuPy 中的内核需要 CUDA 运行时头文件。如果 CuPy 引发 NVRTC_ERROR_COMPILATION，并且错误消息显示 catastrophic error: cannot open source file "vector_types.h"（几乎对所有内容都是如此），则可能是 CuPy 无法在您的系统上正确找到头文件。

如果您已从 conda-forge 安装 CuPy（即执行 conda install -c conda-forge cupy），则不会出现此问题，因为包含所需头文件的包 cuda-cudart-dev_<platform> 已作为依赖项正确安装。如果您在使用 Conda 安装的 CuPy 时遇到问题，请向 CuPy 仓库报告。

如果您已从 PyPI 安装 CuPy（即执行 pip install cupy-cuda12x），您可以通过运行 pip install "nvidia-cuda-runtime-cu12==12.X.*" 来安装 CUDA 头文件，其中 12.X 是您的 CUDA 安装版本。一旦包中的头文件被识别，cupy.show_config() 将显示路径为 CUDA Extra Include Dirs

$ python -c 'import cupy; cupy.show_config()'
...
CUDA Extra Include Dirs      : []
...
NVRTC Version                : (12, 6)
...
$ pip install "nvidia-cuda-runtime-cu12==12.6.*"
...
$ python -c 'import cupy; cupy.show_config()'
...
CUDA Extra Include Dirs      : ['.../site-packages/nvidia/cuda_runtime/include']
...

或者，您可以使用 NVIDIA 的 Apt（或 DNF）仓库系统范围安装 CUDA 头文件（/usr/local/cuda）。安装 cuda-cudart-dev-12-X 包，其中 12-X 是您的 cuda-cudart 包的版本，例如

$ apt list "cuda-cudart-*"
cuda-cudart-12-6/now 12.6.68-1 amd64 [installed,local]
$ sudo apt install "cuda-cudart-dev-12-6"

CuPy 总是引发 cupy.cuda.compiler.CompileException#

如果 CuPy 几乎对所有内容都引发 CompileException，则可能是 CuPy 无法正确检测到您系统上安装的 CUDA。以下是此类情况中常见的错误消息。

  • nvrtc: error: failed to load builtins

  • catastrophic error: cannot open source file "cuda_fp16.h"

  • error: cannot overload functions distinguished by return type alone

  • error: identifier "__half_raw" is undefined

  • error: no instance of overloaded function "__half::__half" matches the specified type

请尝试设置 LD_LIBRARY_PATH 和 CUDA_PATH 环境变量。例如，如果您的 CUDA 安装在 /usr/local/cuda-12.6

$ export CUDA_PATH=/usr/local/cuda-12.6
$ export LD_LIBRARY_PATH=$CUDA_PATH/lib64:$LD_LIBRARY_PATH

另请参阅使用自定义 CUDA 安装。

在 Ubuntu 16.04、CentOS 6 或 7 上构建失败#

要在使用旧版 GCC (g++-5 或更早) 的系统上从源码构建 CuPy，您需要手动设置 g++-6 或更高版本，并配置 NVCC 环境变量。

在 Ubuntu 16.04 上

$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo apt update
$ sudo apt install g++-6
$ export NVCC="nvcc --compiler-bindir gcc-6"

在 CentOS 6 / 7 上

$ sudo yum install centos-release-scl
$ sudo yum install devtoolset-7-gcc-c++
$ source /opt/rh/devtoolset-7/enable
$ export NVCC="nvcc --compiler-bindir gcc"

在 AMD GPU 上使用 CuPy（实验性）#

CuPy 对 AMD GPU (ROCm) 有实验性支持。

要求#

需要以下 ROCm 库

$ sudo apt install hipblas hipsparse rocsparse rocrand hiprand rocthrust rocsolver rocfft hipfft hipcub rocprim rccl roctracer-dev

环境变量#

为 ROCm 构建或运行 CuPy 时，以下环境变量有效。

  • ROCM_HOME: 包含 ROCm 软件的目录（例如 /opt/rocm）。

Docker#

您可以尝试使用 Docker 运行 ROCm 版的 CuPy。

$ docker run -it --device=/dev/kfd --device=/dev/dri --group-add video cupy/cupy-rocm

安装二进制包#

Linux (x86_64) 提供 wheels（预编译二进制包）。包名称因您的 ROCm 版本而异。

ROCm

命令

v4.3

$ pip install cupy-rocm-4-3

v5.0

$ pip install cupy-rocm-5-0

从源码构建 ROCm 版 CuPy#

要从源码构建 CuPy，请设置 CUPY_INSTALL_USE_HIP、ROCM_HOME 和 HCC_AMDGPU_TARGET 环境变量。（HCC_AMDGPU_TARGET 是您的 GPU 支持的 ISA 名称。运行 rocminfo 并使用 Name: 行中显示的值（例如 gfx900）。如果您有不同架构的多个 GPU，可以指定一个逗号分隔的 ISA 列表。）

$ export CUPY_INSTALL_USE_HIP=1
$ export ROCM_HOME=/opt/rocm
$ export HCC_AMDGPU_TARGET=gfx906
$ pip install cupy

注意

如果您未指定 HCC_AMDGPU_TARGET 环境变量，CuPy 将为构建主机上可用的 GPU 架构构建。此行为特定于 ROCm 构建；在为 NVIDIA CUDA 构建 CuPy 时，构建结果不受主机配置的影响。

限制#

由于 ROCm 的限制或它们特定于 CUDA，以下功能不可用

  • CUDA 数组接口

  • cuTENSOR

  • 处理大小接近 32 位边界的超大数组（已知 HIP 在大小为 2**32-1024 时会失败）

  • FP16 中的原子加法（cupy.ndarray.scatter_add 和 cupyx.scatter_add）

  • 多 GPU FFT 和 FFT 回调

  • 一些随机数生成算法

  • RawKernel/RawModule API 中的几个选项：Jitify、动态并行

  • 每线程默认流

以下功能尚不支持

  • 稀疏矩阵（cupyx.scipy.sparse）

  • cuDNN (hipDNN)

  • Hermitian/对称特征值求解器（cupy.linalg.eigh）

  • 多项式根（使用 Hermitian/对称特征值求解器）

  • cupyx.scipy.interpolate 中的样条（make_interp_spline，RegularGridInterpolator/interpn 的样条模式），因为它们依赖于稀疏矩阵。

以下功能在某些边缘情况（例如，某些 dtype 组合）下可能不起作用

注意

我们正在调查问题的根本原因。它们不一定是 CuPy 的问题，但 ROCm 可能存在一些潜在的错误。

  • cupy.ndarray.__getitem__ (#4653)

  • cupy.ix_ (#4654)

  • 一些多项式例程 (#4758, #4759)

  • cupy.broadcast (#4662)

  • cupy.convolve (#4668)

  • cupy.correlate (#4781)

  • 一些随机采样例程（cupy.random，#4770）

  • cupy.linalg.einsum

  • cupyx.scipy.ndimage 和 cupyx.scipy.signal (#4878, #4879, #4880)