Skip to content
Get packs

Guide · Open source

How to use CuPy: install and run NumPy code on a GPU

Updated · written with AI from the project's own documentation and checked against our catalogue data

CuPy is an open-source Python library that mirrors the NumPy and SciPy interfaces but runs array calculations on a GPU. This guide is for Python users who have an NVIDIA GPU and want to move NumPy-style code onto it. By the end you will know what to install, how to run a first array example, and where CuPy fits compared with its alternatives.

CuPycupy/cupy · ★ 12.4k · MIT

Quick start

  1. 1Check your GPU and Python. Confirm you have an NVIDIA GPU with a CUDA driver and a working Python installation.
  2. 2Pick your CUDA version. Match the package to your CUDA version, such as 12.x or 13.x, as listed in the README.
  3. 3Install CuPy. Run pip install cupy-cuda12x or pip install cupy-cuda13x, or use conda install -c conda-forge cupy.
  4. 4Import CuPy. Use import cupy as cp in your script, following the convention in the README example.
  5. 5Run a small array example. Create an array with cp.arange, reshape it and call sum to confirm the GPU path works.
  6. 6Port an existing NumPy script. Swap the NumPy import for CuPy where the functions match, then test the results against your original output.

What CuPy is and what you need before installing

CuPy is a NumPy/SciPy-compatible array library for GPU-accelerated computing with Python. The README describes it as a drop-in replacement that runs existing NumPy and SciPy code on NVIDIA CUDA or AMD ROCm platforms.

The main prerequisites are Python and an NVIDIA GPU with a CUDA driver. CuPy is built around GPU hardware, so it is not a good fit for machines without a supported GPU.

  • Python installed on your machine
  • An NVIDIA GPU with a CUDA driver
  • AMD GPUs are listed through ROCm, but the README marks the ROCm 7.0 install as experimental

Install CuPy with pip

Binary packages (wheels) are available for Linux and Windows on PyPI. Choose the package that matches your CUDA version. The README lists the following commands.

Pre-release builds can be installed with an extra flag and index, as shown in the README note.

  • CUDA 12.x: pip install cupy-cuda12x
  • CUDA 13.x: pip install cupy-cuda13x
  • ROCm 7.0 (experimental): pip install cupy-rocm-7-0
pip install cupy-cuda12x

Install CuPy with conda

Binary packages are also available for Linux and Windows on Conda-Forge. The README gives a basic command for the default CUDA setup.

If you need a slim installation without CUDA dependencies, the README suggests installing cupy-core instead. To pick a particular CUDA version, use the cuda-version metapackage as shown in the README.

  • Slim install: conda install -c conda-forge cupy-core
  • Specific CUDA version: conda install -c conda-forge cupy cuda-version=12.0
conda install -c conda-forge cupy

Run your first CuPy array code

CuPy is imported as cp and most functions look like their NumPy equivalents. The example below creates a 2 by 3 array, converts it to float32 and sums each row on the GPU.

Because the API matches NumPy, existing scripts often need only the import changed and some array creation calls updated. Check the README's comparison page before assuming a script will run unchanged.

import cupy as cp x = cp.arange(6).reshape(2, 3).astype('f') x.sum(axis=1)

Use Docker if you prefer containers

CuPy container images are published on Docker Hub. To run them you need the NVIDIA Container Toolkit, as the README notes.

  • Requires the NVIDIA Container Toolkit
docker run --gpus all -it cupy/cupy

Go further with low-level CUDA features

Beyond array operations, CuPy exposes low-level CUDA features. You can pass ndarray objects to existing CUDA C/C++ programs through RawKernels, use Streams for performance, or call CUDA Runtime APIs directly.

The official tutorial and API reference are the best next stops for these topics.

  • RawKernels: pass arrays to your own CUDA C/C++ kernels
  • Streams: available for performance tuning
  • CUDA Runtime APIs: callable directly from Python

What people use it for

  • Speeding up NumPy-style array calculations in a Python script on an NVIDIA GPU
  • Moving existing NumPy or SciPy research code onto a GPU with few changes
  • Calling your own CUDA C/C++ kernels from Python using CuPy arrays
  • Running CuPy inside a container with the NVIDIA Container Toolkit

Frequently asked questions

Is CuPy free to use?

CuPy is released under the MIT License, as stated in the README. The license file is named LICENSE in the repository.

What do I need to install CuPy?

You need Python and an NVIDIA GPU with a CUDA driver. The README also lists AMD support through ROCm 7.0, which it marks as experimental.

Which pip package should I install?

Install cupy-cuda12x for CUDA 12.x or cupy-cuda13x for CUDA 13.x, as shown in the README. For AMD ROCm 7.0 the package is cupy-rocm-7-0.

How is CuPy different from NumPy?

CuPy has a NumPy and SciPy compatible interface but runs the calculations on a GPU. The README describes it as a drop-in replacement for existing NumPy or SciPy code.

What are the alternatives to CuPy?

The comparable projects listed are NumPy, PyTorch, JAX and Numba. NumPy runs on the CPU, while the others offer their own GPU-oriented approaches.

Why is my CuPy code not faster?

Small workloads can lose time moving data to the GPU, so the computation may not save enough to pay for the transfer. This is general reasoning rather than a claim from the README.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

CuPy suits Python users with NVIDIA GPUs who want to speed up NumPy or SciPy style array code, or call their own CUDA kernels from Python. If you have no supported GPU, or your workloads are small, stick with NumPy or consider PyTorch, JAX or Numba for other approaches.

Install options & downloads