Install & Compatibility
Where this runs
tested against v0.30.2 · 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
py 3.10
✕ build_error
✓ 8.6s
py 3.11
✕ build_error
✓ 8.3s
py 3.12
✕ build_error
✓ 8.5s
py 3.13
✕ build_error
✓ 8.38s
py 3.9
✕ build_error
✕ build_error
335MB installed
● package 335MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cuda
✓ from numba import cuda
All CUDA-specific functionality is exposed through the `numba.cuda` module.
This quickstart demonstrates a basic vector addition using a Numba CUDA kernel. It covers defining a kernel with `@cuda.jit`, allocating and transferring data between host (CPU) and device (GPU) memory, configuring and launching the kernel, and copying results back to the host. Ensure you have a CUDA-enabled GPU and appropriate drivers installed.
import numpy as np
from numba import cuda
import os
# Check for CUDA availability (runtime dependency)
if not cuda.is_available():
print("CUDA is not available. Please ensure you have an NVIDIA GPU and CUDA drivers installed.")
exit()
# Define a CUDA kernel
@cuda.jit
def add_vectors(x, y, out):
idx = cuda.grid(1)
if idx < len(out):
out[idx] = x[idx] + y[idx]
# Host-side code
N = 1000000
x_host = np.arange(N, dtype=np.float32)
y_host = np.arange(N, dtype=np.float32)
out_host = np.empty_like(x_host)
# Allocate memory on the device and copy data
x_device = cuda.to_device(x_host)
y_device = cuda.to_device(y_host)
out_device = cuda.device_array_like(out_host)
# Configure the kernel launch
threadsperblock = 256
blockspergrid = (N + (threadsperblock - 1)) // threadsperblock
# Launch the kernel
add_vectors[blockspergrid, threadsperblock](x_device, y_device, out_device)
# Copy the result back to the host
out_device.copy_to_host(out_host)
# Verify the result
expected_out = x_host + y_host
assert np.allclose(out_host, expected_out)
print("Vector addition on GPU successful!")
Debug
Known issues
deprecatedThe built-in CUDA target in the main `numba` package is deprecated. New features and most bug fixes are now exclusively implemented in `numba-cuda`. While the old target remains for compatibility, it's strongly recommended to install `numba-cuda` for active development and to ensure access to the latest capabilities.fixAlways include `pip install numba-cuda` (or `conda install numba-cuda`) in your environment setup alongside `numba`.
affects: Numba v0.61.0 and later when not explicitly installing numba-cuda.
breakingIn `numba-cuda` v0.28.0, there was an attempt to shift error classes from `numba.core.errors.TypingError` to `numba.cuda.errors` namespaces. This caused compatibility issues with existing code that relied on catching the old error types and was subsequently reverted. Users should be aware that such internal error type changes can be breaking.fixEnsure your `try-except` blocks are robust to potential changes in error types. For maximum compatibility, catch broader exception types or consult release notes if you encounter unexpected `TypingError` propagation.
affects: v0.28.0 (reverted in subsequent patches)
breakingThe internal `DeviceArray` implementation underwent refactoring, and certain internal `enums` and `ctypes` code were removed in `numba-cuda` v0.23.0 and v0.28.0 respectively. Code that directly interacted with these internal components or undocumented APIs may break.fixAvoid relying on Numba's internal implementation details. Stick to the public API documented in `numba.cuda` for memory management (`cuda.to_device`, `cuda.device_array`), kernel launching, and device interactions.
affects: v0.23.0, v0.28.0
gotchaNumba CUDA kernel functions cannot return values. Any results computed within a kernel must be written to arrays passed as arguments to the kernel. This is a common pattern in CUDA C/C++ and applies to Numba CUDA kernels as well.fixPass empty or pre-allocated device arrays as arguments to your kernel, and have the kernel write its output into these arrays. Copy the results back to the host after kernel execution if needed.
affects: All versions
gotchaThe first call to a Numba CUDA kernel includes the Just-In-Time (JIT) compilation overhead, which can be significant. For accurate performance benchmarking, always time subsequent calls to the kernel after the initial compilation has completed (e.g., by performing a 'warm-up' run).fixRun your kernel once with dummy data to trigger compilation, then measure the execution time of subsequent calls. Use `cuda.synchronize()` to ensure all GPU operations have completed before measuring elapsed time.
affects: All versions
breakingSupport for NVIDIA GPUs with compute capability less than 5.0 is deprecated and will be removed in future releases. Additionally, Numba-CUDA requires a minimum CUDA Toolkit version of 11.2.fixEnsure your target GPU has compute capability 5.0 or higher. Upgrade your NVIDIA drivers and CUDA Toolkit to version 11.2 or newer.
affects: All versions (deprecation active)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'numba.cuda'
This error occurs when the `numba-cuda` package, or the `numba` package which includes CUDA support, is not installed or not correctly accessible in the Python environment being used.
fixEnsure `numba-cuda` is installed using `pip install numba-cuda` or, if using Anaconda, `conda install -c nvidia numba-cuda`. For older Numba installations where CUDA was part of the main package, use `conda install numba cudatoolkit`.
numba.cuda.cudadrv.error.CudaSupportError: Error at driver init: Call to cuInit results in CUDA_ERROR_NO_DEVICE (100)
Numba-CUDA cannot find or initialize a compatible CUDA-enabled GPU device, often due to missing or incorrectly installed NVIDIA GPU drivers, CUDA Toolkit, or issues with environment variables (e.g., `LD_LIBRARY_PATH`).
fixVerify that NVIDIA GPU drivers are installed and up-to-date, that the CUDA Toolkit is installed and its paths (e.g., `CUDA_HOME`, `PATH`, `LD_LIBRARY_PATH`) are correctly configured, and that a CUDA-enabled GPU is present and functional. Restarting the system can sometimes resolve temporary driver issues. On Linux with `multiprocessing`, ensure CUDA is not initialized before forking processes.
numba.cuda.cudadrv.driver.CudaAPIError: [1] Call to cuLaunchKernel results in CUDA_ERROR_INVALID_VALUE
This runtime error typically indicates an issue with the parameters passed to a CUDA kernel launch, such as invalid grid or block dimensions, an incorrect shared memory size, or attempting to access device memory out of bounds.
fixCarefully review the `blockspergrid` and `threadsperblock` arguments passed to your CUDA kernel and ensure they are valid for your GPU and array sizes. Check any dynamic shared memory allocations and boundary conditions within your kernel logic.
numba.cuda.cudadrv.driver.CudaAPIError: [CUresult.CUDA_ERROR_UNSUPPORTED_PTX_VERSION]
This error means there's a mismatch between the PTX (Parallel Thread Execution) version generated by Numba and the PTX version supported by your installed CUDA driver and toolkit. This often happens after a GPU driver update or when using different versions of CUDA Toolkit during compilation and runtime.
fixEnsure that your CUDA Toolkit version is compatible with your NVIDIA GPU driver. If using `conda`, installing `cudatoolkit` via `conda install cudatoolkit` ensures a compatible version is used with Numba. You might need to update or downgrade your CUDA Toolkit/driver to match the supported PTX version. For Numba, you can specify the compute capability (sm_XX) for compilation if needed.
numba.errors.TypingError: Failed in nopython mode pipeline (step: nopython frontend) type object 'numpy.int64' has no attribute 'is_precise'
This `TypingError` occurs when Numba's type inference fails, often because of incompatible data types used within a CUDA kernel, particularly when mixing standard NumPy types with Numba's internal types or when Numba cannot determine a unified type.
fixEnsure that data types used within your Numba CUDA kernel are explicitly defined and compatible with Numba's type system. Prefer `numba.types` (e.g., `numba.types.int64`) over `numpy` types (e.g., `np.int64`) for device functions and array allocation within CUDA kernels. Debugging with `@cuda.jit(debug=True)` can help identify the exact location of type inference failure.
Upgrade
Version history
0.30.2latest on PyPI · released May 12, 2026
Audit
Dependencies
numbarequiredCore JIT compiler, numba-cuda is a target extension.
numpyrequiredKernels often operate on NumPy arrays, which are automatically transferred to/from the device.
cuda-pythonrequiredUsed for NVVM bindings and interacting with the CUDA Driver API (since v0.29.0).
cudatoolkitoptionalRuntime dependency for CUDA-enabled GPUs; required for compilation and execution. Install via `conda` or NVIDIA CUDA SDK.