Install & Compatibility
Where this runs
tested against v14.1.1 · 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.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 14.2s · import 0.723s · 283MB
274MB installed
● package 274MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cupy
✓ import cupy as cp
Standard convention for importing CuPy.
cupyx.scipy
✓ import cupyx.scipy as cpxs
✗ import cupy.scipy
SciPy-compatible functions are located under the `cupyx.scipy` submodule, not directly under `cupy.scipy`.
This quickstart demonstrates basic CuPy array creation, arithmetic operations on the GPU, transferring data between GPU and CPU, and performing a NumPy-like aggregation. It includes a check for GPU availability and the use of `cp.cuda.Stream.null.synchronize()` for explicit GPU synchronization, which is important for accurate performance measurement.
import cupy as cp
import numpy as np
# Check if a GPU is available
if cp.cuda.is_available():
print(f"CuPy 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(f"GPU array:\n{x_gpu}")
print(f"Type of GPU array: {type(x_gpu)}")
# Perform a computation on the GPU
y_gpu = x_gpu * 2 + 1
print(f"Result of computation on GPU:\n{y_gpu}")
# Transfer the result back to CPU NumPy array
y_cpu = cp.asnumpy(y_gpu)
print(f"CPU array (from GPU):\n{y_cpu}")
print(f"Type of CPU array: {type(y_cpu)}")
# Demonstrate a simple NumPy-like operation
sum_gpu = x_gpu.sum(axis=1)
print(f"Sum along axis 1 on GPU: {sum_gpu}")
print(f"Type of sum on GPU: {type(sum_gpu)}")
# Ensure all GPU operations complete before proceeding (useful for timing)
cp.cuda.Stream.null.synchronize()
else:
print("No NVIDIA GPU found or CuPy is not properly installed for CUDA.")
print("Falling back to NumPy for demonstration.")
x_cpu = np.arange(10, dtype=np.float32).reshape(2, 5)
print(f"CPU array:\n{x_cpu}")
Debug
Known issues
breakingCuPy v14 aligns its behavior with NumPy 2 semantics, which includes changes to type promotion rules and casting behavior. Code relying on older NumPy 1.x type promotion might behave differently.fixReview and adapt code for NumPy 2 compatibility. Refer to NumPy 2 and CuPy v14 release notes for detailed changes.
affects: 14.x.x and above
breakingCuPy v14 has completely removed all cuDNN-related functionality. Direct usage of `cupy.cuda.cudnn` will fail.fixMigrate any cuDNN-dependent code to use `cuDNN Frontend` directly or other libraries that wrap cuDNN functionality.
affects: 14.x.x and above
breakingSupport for CUDA 11 and Python 3.9 has been dropped in CuPy v14. Users on these older environments must upgrade.fixUpgrade to CUDA Toolkit 12.x or 13.x and Python 3.10 or newer.
affects: 14.x.x and above
gotchaInstalling `cupy-cuda13x` requires a compatible NVIDIA CUDA Toolkit 13.x installation or driver. Mismatches in CUDA versions between the installed CuPy wheel and the system's CUDA Toolkit can lead to `ImportError` or runtime compilation errors.fixEnsure your system's CUDA Toolkit version (specifically the driver) matches the `cupy-cudaXXx` package you install. For easier setup without a full system CUDA Toolkit, use `pip install 'cupy-cuda13x[ctk]'` to install PyPI-distributed CUDA components.
affects: All versions tied to specific CUDA major versions (e.g., cupy-cuda13x)
gotchaInitial execution of CuPy functions can be slower than subsequent calls due to just-in-time compilation and caching of CUDA kernels.fixThis is expected behavior and typically not an issue for repeated operations. For performance-critical loops, ensure initialization or a 'warm-up' run occurs outside the timed section.
affects: All versions
gotchaGPU operations in CuPy are asynchronous by default. For accurate timing of GPU execution in benchmarks or to ensure operations complete before host interaction, explicit synchronization is necessary.fixCall `cp.cuda.Stream.null.synchronize()` after the GPU computation and before measuring time or accessing results on the CPU.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cupy'
CuPy was either not installed in the active Python environment, or environment variables (like PATH) were not reloaded after installation, particularly when installing a CUDA Toolkit.
fixEnsure you are in the correct virtual environment. If CuPy was just installed, restart your Python script, IDE, or terminal to refresh environment variables. Verify installation with `pip freeze | grep cupy`.
TypeError: Argument 'x' has incorrect type (expected cupy.core.core.ndarray, got numpy.ndarray)
Attempting to pass a NumPy array (CPU-resident) directly to a CuPy function that expects a CuPy array (GPU-resident).
fixConvert the NumPy array to a CuPy array using `cp.asarray()` or `cp.array()` before passing it to CuPy functions. Example: `gpu_array = cp.asarray(numpy_array)`.
cupy.cuda.compiler.CompileException: nvrtc: error: failed to load builtins; catastrophic error: cannot open source file "cuda_fp16.h"
CuPy's CUDA compiler (NVRTC) cannot find necessary CUDA header files, often due to an incorrect or incomplete CUDA Toolkit installation, or an environment variable (`CUDA_PATH`, `LD_LIBRARY_PATH`) not being set correctly.
fixVerify your CUDA Toolkit installation. Ensure `CUDA_PATH` or `LD_LIBRARY_PATH` are set if CUDA is in a non-standard location. If using PyPI `[ctk]` installation, make sure the `nvidia-cuda-runtime-cuXX` package is correctly installed to provide headers. You might need to explicitly install `cuda-cudart-dev-12-X` (for CUDA 12) or similar `cuda-cudart-dev-13-X` for CUDA 13.
TypeError: Implicit conversion to a NumPy array is not allowed. Please use `.get()` to construct a NumPy array explicitly.
Attempting to implicitly convert a CuPy array to a NumPy array in contexts where explicit conversion is required, such as direct interaction with NumPy-only functions or printing large arrays.
fixExplicitly convert the CuPy array to a NumPy array using `cupy.asnumpy()` or the `.get()` method. For example: `cpu_array = gpu_array.get()` or `cpu_array = cp.asnumpy(gpu_array)`.
Upgrade
Version history
14.1.1latest on PyPI · released Jun 1, 2026
Audit
Dependencies
NVIDIA CUDA GPUrequiredRequired hardware with Compute Capability 3.0 or larger for GPU acceleration.
NVIDIA CUDA Toolkit 13.xoptionalRequired for compiling and running CUDA kernels. This specific wheel targets CUDA 13.x. Can be avoided with `[ctk]` extra if using PyPI CUDA components.
numpyrequiredCuPy is NumPy-compatible and relies on NumPy's API and structure.
scipyoptionalOptional for SciPy-compatible functions via `cupyx.scipy`.
ml_dtypesoptionalRequired for `bfloat16` data type support introduced in CuPy v14.
cutensor-cu13optionalOptional for additional cuTENSOR library features.
nvidia-nccl-cu13optionalOptional for additional NCCL library features (multi-GPU/multi-node collective operations).