安装#

要求#

  • 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

    • 如果你安装了多个版本的 CUDA Toolkit,CuPy 会自动选择其中一个 CUDA 安装。详情请参阅 使用自定义 CUDA 安装

    • 如果你从 conda-forge 安装 CuPy,这个要求是可选的。然而,你仍然需要为你的 GPU 安装一个兼容的驱动程序。详情请参阅 从 Conda-Forge 安装 CuPy

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

备注

目前,CuPy 针对 Ubuntu 20.04 LTS / 22.04 LTS (x86_64)、CentOS 7 / 8 (x86_64) 和 Windows Server 2016 (x86_64) 进行了测试。

Python 依赖项#

CuPy v14 中兼容 NumPy/SciPy 的 API 基于 NumPy 2.1 和 SciPy 1.14,并已针对以下版本进行了测试:

备注

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

备注

在安装 CuPy 之前,我们建议您升级 setuptoolspip:

$ python -m pip install -U setuptools pip

附加的CUDA库#

CuPy 中的部分 CUDA 功能只有在安装了相应的库时才会被激活。

  • cuTENSOR: v2.0

    • 用于加速张量操作的库。详情请参阅 环境变量

  • NCCL: v2.16 / v2.17

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

  • cuDNN: v8.8

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

  • cuSPARSELt: v0.6.0 / v0.6.1

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

安装 CuPy#

从 PyPI 安装 CuPy#

轮子(预编译的二进制包)适用于 Linux 和 Windows。包名称根据您的 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)提供的功能,您需要手动安装它们。如果您通过 wheel 文件安装了 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)。

使用轮子时,请注意不要同时安装多个 CuPy 包。这些包中的任何一个和 cupy 包(源安装)都会相互冲突。请确保只安装一个 CuPy 包(cupycupy-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 轮子安装。

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-forgecudatoolkit 包不包含 nvcc 编译器工具链。如果你希望从本地 CUDA 安装中使用它,你需要确保 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 版本号)。

备注

如果通过 conda 安装了 CuPy,请改为执行 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#

请确保您使用的是最新版本的 setuptoolspip:

$ 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,可能会在构建 CuPy 时遇到错误 g++: error: unrecognized command line option ‘-R’。这是由于 conda 中的一个 bug 导致的(详见 conda/conda#6030)。如果你遇到这个问题,请升级你的 conda。

安装 cuDNN 和 NCCL#

我们建议使用NVIDIA提供的二进制包(即使用 aptyum)来安装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 之前使用 CFLAGSLDFLAGSLD_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 Runtime 头文件。如果 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: 错误: 加载内置函数失败

  • 灾难性错误:无法打开源文件“cuda_fp16.h”

  • 错误: 不能仅通过返回类型来重载函数

  • 错误:标识符“__half_raw”未定义

  • 错误:没有匹配指定类型的重载函数“__half::__half”的实例

请尝试设置 LD_LIBRARY_PATHCUDA_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)。包名称因您的 ROCm 版本而异。

ROCm

命令

v4.3

$ pip install cupy-rocm-4-3

v5.0

$ pip install cupy-rocm-5-0

从源代码构建适用于 ROCm 的 CuPy#

要从源代码构建 CuPy,请设置 CUPY_INSTALL_USE_HIPROCM_HOMEHCC_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_addcupyx.scatter_add

  • 多GPU FFT 和 FFT 回调

  • 一些随机数生成算法

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

  • 每个线程的默认流

以下功能尚未支持:

  • 稀疏矩阵 (cupyx.scipy.sparse)

  • cuDNN (hipDNN)

  • Hermitian/对称特征值求解器 (cupy.linalg.eigh)

  • 多项式根(使用厄米特/对称特征值求解器)

  • cupyx.scipy.interpolate 中的样条曲线(make_interp_splineRegularGridInterpolator/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.ndimagecupyx.scipy.signal (#4878, #4879, #4880)