Install & Compatibility
Where this runs
tested against v14.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 21.7s · import 0.857s · 370MB
361MB installed
● package 361MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cupy
✓ import cupy as cp
Standard alias, similar to 'import numpy as np'.
cupyx.scipy
✓ import cupyx.scipy as sp
For SciPy-compatible routines on GPU.
This quickstart demonstrates basic CuPy array creation, GPU computation, and data transfer between the GPU and CPU. It also includes a check for GPU availability and emphasizes `cp.cuda.Stream.null.synchronize()` for accurate benchmarking, as GPU operations are often asynchronous.
import cupy as cp
import numpy as np
# Check if a GPU is available
if cp.cuda.is_available():
print("GPU is available. Current device:", cp.cuda.Device().id)
# Create a CuPy array on the GPU
x_gpu = cp.arange(10, dtype=cp.float32).reshape(2, 5)
print("CuPy array on GPU:\n", x_gpu)
# Perform an operation on the GPU
y_gpu = x_gpu * 2 + 1
print("Result of GPU operation:\n", y_gpu)
# Transfer the result back to CPU (NumPy array)
y_cpu = cp.asnumpy(y_gpu)
print("Result on CPU (NumPy array):\n", y_cpu)
# Example: Dot product
a_gpu = cp.array([[1, 2], [3, 4]], dtype=cp.float32)
b_gpu = cp.array([[5, 6], [7, 8]], dtype=cp.float32)
c_gpu = a_gpu @ b_gpu
print("\nMatrix multiplication on GPU:\n", c_gpu)
# For accurate performance timings, ensure GPU operations complete
cp.cuda.Stream.null.synchronize()
else:
print("No GPU available. CuPy will not be functional.")
Debug
Known issues
breakingCuPy v14 updates its type promotion rules and casting behavior to align with NumPy v2 semantics. Code relying on NumPy v1 specific behaviors in earlier CuPy versions (v13 and prior) may behave differently.fixReview code for type-sensitive operations, especially when mixing dtypes or interacting with NumPy arrays, and adjust for NumPy v2 compatibility. Test thoroughly.
affects: 14.0.0 and later
breakingCuPy v14 drops support for CUDA 11 and Python 3.9. Additionally, all cuDNN-related functionality has been completely removed from CuPy. Users requiring cuDNN should consider external libraries like cuDNN Frontend.fixUpgrade to Python 3.10+ and a compatible CUDA Toolkit version (12.x for `cupy-cuda12x`). If cuDNN is needed, integrate an alternative Python binding for cuDNN.
affects: 14.0.0 and later
gotchaCuPy uses a memory pool for GPU allocations. This means GPU memory might not be immediately released back to the system even after arrays go out of scope, which can cause utilities like `nvidia-smi` to report higher memory usage than expected.fixWhile generally beneficial for performance, for long-running processes or when strict memory limits are needed, use `cp.get_default_memory_pool().free_all_blocks()` to explicitly release unused cached memory. Monitor fragmentation with `cp.cuda.get_memory_info()`.
affects: All versions
gotchaFrequent data transfers between CPU (host) and GPU (device) are a major performance bottleneck due to PCIe bandwidth limitations. Avoid 'round-tripping' arrays in hot loops.fixKeep data on the GPU as much as possible for computations. Perform all necessary operations on CuPy arrays directly. Transfer data to CPU only when the final result is needed or for visualization/storage.
affects: All versions
gotchaThe first time a CuPy kernel is called for specific shapes and data types, it may experience a brief pause for JIT compilation. Subsequent calls with the same parameters will use the cached, pre-compiled kernel.fixThis is expected behavior and generally not a problem in long-running applications. For benchmarking or time-critical initial runs, consider a warm-up execution or factor in the first-call compilation time.
affects: All versions
gotchaInstalling a `cupy-cudaXX` package that does not match your system's CUDA Toolkit version or compatible driver can lead to import failures or runtime errors.fixEnsure the `cupy-cudaXX` package suffix matches your installed CUDA version (e.g., `cupy-cuda12x` for CUDA 12.x). If using PyPI `[ctk]` extras, only a compatible CUDA driver is required. Refer to CuPy's installation matrix for exact compatibility.
affects: All versions
breakingIn CuPy v13+, the default behavior for transferring NumPy arrays backed by pinned memory from CPU to GPU (`cupy.array()`, `cupy.asarray()`) changed from blocking to asynchronous. This can improve performance but may introduce data races if the source array is modified on the CPU before the asynchronous transfer completes.fixIf explicit blocking is required to prevent data races, use the `blocking=True` argument when calling `cp.array()` or `cp.asarray()`.
affects: 13.0.0 and later
Errors
Common errors & fixes
ImportError: libcudart.so.12: cannot open shared object file: No such file or directory
CuPy cannot find the necessary CUDA runtime library (`libcudart.so.12`), often due to an incorrect or incomplete CUDA Toolkit installation or an improperly configured `LD_LIBRARY_PATH` environment variable.
fixEnsure the CUDA Toolkit 12.x is correctly installed and that the directory containing `libcudart.so.12` (e.g., `/usr/local/cuda-12.x/lib64`) is added to your `LD_LIBRARY_PATH`. For PyPI installations, you might also need to install `nvidia-cuda-runtime-cu12`: `pip install "nvidia-cuda-runtime-cu12==12.X.*"` (replace 12.X with your CUDA version).
cupy.cuda.runtime.CUDARuntimeError: cudaErrorNoDevice: no CUDA-capable device is detected
CuPy failed to detect an available CUDA-enabled GPU, which can happen if no NVIDIA GPU is present, drivers are not installed or are outdated, or the `CUDA_VISIBLE_DEVICES` environment variable is incorrectly set (e.g., set to an empty string or an invalid device ID).
fixVerify that you have an NVIDIA GPU and that its drivers are correctly installed. Ensure `CUDA_VISIBLE_DEVICES` is not set to an empty string; if you need to specify devices, use valid indices (e.g., `export CUDA_VISIBLE_DEVICES=0`).
cupy.cuda.runtime.CUDARuntimeError: cudaErrorInitializationError: initialization error
This error commonly occurs when using CuPy with Python's `multiprocessing` module, as CUDA contexts cannot be safely inherited across processes created with the default 'fork' start method.
fixBefore creating any multiprocessing pools or processes, explicitly set the multiprocessing start method to 'spawn' or 'forkserver': `import multiprocessing; multiprocessing.set_start_method('spawn', force=True)`. NVRTC_ERROR_COMPILATION (6): catastrophic error: cannot open source file "vector_types.h"
CuPy fails to compile CUDA kernels because it cannot find the necessary CUDA Runtime header files, which is particularly common with CUDA 12.2 and later versions if the headers are not installed or correctly located.
fixIf installed via PyPI (`pip install cupy-cuda12x`), explicitly install the CUDA runtime headers: `pip install "nvidia-cuda-runtime-cu12==12.X.*"` (replace 12.X with your CUDA version). Alternatively, ensure the CUDA Toolkit and its development headers are installed system-wide.
Upgrade
Version history
14.2.0latest on PyPI · released Aug 20, 2026
Audit
Dependencies
numpyrequiredCore dependency for array functionality and API compatibility.
scipyoptionalOptional, required for SciPy-compatible routines (e.g., sparse matrices, signal processing, special functions).
ml_dtypesoptionalOptional, required for bfloat16 data type support (CuPy v14+).
CUDA driverrequiredSystem-level dependency for NVIDIA GPUs. A compatible driver must be installed regardless of how CuPy or CUDA Toolkit components are installed.