Installation Guide

Dependencies

Before installing CuPy, we recommend to upgrade setuptools if you are using an old one:

$ pip install -U setuptools

The following Python packages are required to install CuPy. The latest version of each package will automatically be installed if missing.

  • NumPy 1.9, 1.10, 1.11, 1.12, 1.13
  • Six 1.9+

In addition, you need to install CUDA. The following versions of CUDA can be used: 7.0, 7.5, 8.0 and 9.0.

Optional Libraries

The following libraries are optional dependencies. CuPy will enable these features only if they are installed.

Install CuPy

Install CuPy via pip

We recommend to install CuPy via pip:

$ pip install cupy

Note

All optional CUDA related libraries, cuDNN and NCCL, need to be installed before installing CuPy. After you update these libraries, please reinstall CuPy because you need to compile and link to the newer version of them.

Install CuPy from source

The tarball of the source tree is available via pip download cupy or from the release notes page. You can install CuPy from the tarball:

$ pip install cupy-x.x.x.tar.gz

You can also install the development version of CuPy from a cloned Git repository:

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

When an error occurs…

Use -vvvv option with pip command. That shows all logs of installation. It may help you:

$ pip install cupy -vvvv

Install CuPy with CUDA

You need to install CUDA Toolkit before installing CuPy. If you have CUDA in a default directory or set CUDA_PATH correctly, CuPy installer finds CUDA automatically:

$ pip install cupy

Note

CuPy installer looks up CUDA_PATH environment variable first. If it is empty, the installer looks for nvcc command from PATH environment variable and use its parent directory as the root directory of CUDA installation. If nvcc command is also not found, the installer tries to use the default directory for Ubuntu /usr/local/cuda.

If you installed CUDA into a non-default directory, you need to specify the directory with CUDA_PATH environment variable:

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

If you want to use a custom nvcc compiler (For example, to use ccache ), please set NVCC environment variables before installing CuPy:

export NVCC='ccache nvcc'

Warning

If you want to use sudo to install CuPy, note that sudo command initializes all environment variables. Please specify CUDA_PATH environment variable inside sudo like this:

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

Install CuPy with cuDNN and NCCL

cuDNN is a library for Deep Neural Networks that NVIDIA provides. NCCL is a library for collective multi-GPU communication. CuPy can use cuDNN and NCCL. If you want to enable these libraries, install them before installing CuPy. We recommend you to install developer library of deb package of cuDNN and NCCL.

If you want to install tar-gz version of cuDNN, we recommend you to install it to CUDA directory. For example if you uses Ubuntu Linux, copy .h files to include directory and .so files to lib64 directory:

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

The destination directories depend on your environment.

If you want to use cuDNN or NCCL installed in other directory, please use CFLAGS, LDFLAGS and LD_LIBRARY_PATH environment variables before installing CuPy:

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

Note

Use full paths for the environment variables. distutils that is used in the setup script does not parse the home directory mark ~.

Install CuPy for developers

CuPy uses Cython (>=0.24). Developers need to use Cython to regenerate C++ sources from pyx files. We recommend to use pip with -e option for editable mode:

$ pip install -U cython
$ cd /path/to/cupy/source
$ pip install -e .

Users need not to install Cython as a distribution package of CuPy only contains generated sources.

Uninstall CuPy

Use pip to uninstall CuPy:

$ pip uninstall cupy

Note

When you upgrade Chainer, pip sometimes install the new version without removing the old one in site-packages. In this case, pip uninstall only removes the latest one. To ensure that Chainer is completely removed, run the above command repeatedly until pip returns an error.

Upgrade CuPy

Just use pip with -U option:

$ pip install -U cupy

Reinstall CuPy

If you want to reinstall CuPy, please uninstall CuPy and then install it. We recommend to use --no-cache-dir option as pip sometimes uses cache:

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

When you install CuPy without CUDA, and after that you want to use CUDA, please reinstall CuPy. You need to reinstall CuPy when you want to upgrade CUDA.

Run CuPy with Docker

We are providing the official Docker image. Use nvidia-docker command to run CuPy image with GPU. You can login to the environment with bash, and run the Python interpreter:

$ nvidia-docker run -it cupy/cupy /bin/bash

Or run the interpreter directly:

$ nvidia-docker run -it cupy/cupy /usr/bin/python

FAQ

Warning message “cuDNN is not enabled” appears

You failed to build CuPy with cuDNN. If you don’t need cuDNN, ignore this message. Otherwise, retry to install CuPy with cuDNN. -vvvv option helps you. See Install CuPy with cuDNN and NCCL.