安装#
要求#
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,并已针对以下版本进行了测试:
NumPy: v1.24 / v1.25 / v1.26 / v2.0 / v2.1
SciPy (可选): v1.10 / v1.11 / v1.12 / v1.13 / v1.14
仅在将稀疏矩阵从GPU复制到CPU时需要(参见 稀疏矩阵 (cupyx.scipy.sparse))。
Optuna (可选): v3.x
仅在使用 自动内核参数优化 (cupyx.optimizing) 时需要。
备注
SciPy 和 Optuna 是可选依赖项,不会自动安装。
备注
在安装 CuPy 之前,我们建议您升级 setuptools
和 pip
:
$ 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) |
|
v12.x (x86_64 / aarch64) |
|
备注
要启用由附加 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 包(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
轮子安装。
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 安装中使用它,你需要确保 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#
请确保您使用的是最新版本的 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,可能会在构建 CuPy 时遇到错误 g++: error: unrecognized command line option ‘-R’
。这是由于 conda 中的一个 bug 导致的(详见 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 安装目录。
CUDA_PATH
环境变量。nvcc
命令的父目录。CuPy 从PATH
环境变量中查找nvcc
命令。/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_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)。包名称因您的 ROCm 版本而异。
ROCm |
命令 |
---|---|
v4.3 |
|
v5.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
)多项式根(使用厄米特/对称特征值求解器)
cupyx.scipy.interpolate
中的样条曲线(make_interp_spline
,RegularGridInterpolator
/interpn
的样条模式),因为它们依赖于稀疏矩阵。
以下功能在边缘情况下可能无法正常工作(例如,某些 dtype 的组合):
备注
我们正在调查问题的根本原因。这些问题不一定是CuPy的问题,但ROCm可能存在一些潜在的错误。