Install & Compatibility
Where this runs
tested against v13.3.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.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.000s · 124MB
124MB installed
● package 124MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cuda_driver
✓ import cuda.cuda_driver as drv
For direct access to the low-level CUDA Driver API.
cuda_runtime
✓ import cuda.cuda_runtime as rt
For access to the CUDA C Runtime API wrappers.
cudart
✓ from cuda import cudart
An alternative import for the CUDA C Runtime API, often used for compatibility with other libraries.
This quickstart initializes the CUDA Driver API and queries the number of available CUDA-enabled GPUs on the system, printing their names. It demonstrates basic interaction with the driver API and includes error handling for common CUDA-related issues.
import cuda.cuda_driver as drv
try:
# Initialize the CUDA driver API
# The '0' indicates the flags for initialization, 0 means default.
drv.cuInit(0)
# Get the number of available CUDA devices
err, device_count = drv.cuDeviceGetCount()
if err == drv.CUresult.CUDA_SUCCESS:
print(f"Successfully initialized CUDA. Found {device_count} CUDA devices.")
for i in range(device_count):
err, device = drv.cuDeviceGet(i)
if err == drv.CUresult.CUDA_SUCCESS:
# Get device name (256 is max length)
err, name_bytes = drv.cuDeviceGetName(256, device)
if err == drv.CUresult.CUDA_SUCCESS:
# Decode the bytes to string and strip null terminators
device_name = name_bytes.decode('utf-8').strip('\x00')
print(f" Device {i}: {device_name}")
else:
print(f"Failed to get CUDA device count. Error: {err.name}")
except drv.CUError as e:
print(f"A CUDA driver error occurred: {e}. Ensure CUDA Toolkit and drivers are installed correctly and compatible.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe `cuda-python` package itself does NOT install the CUDA Toolkit or NVIDIA drivers. These are system-level prerequisites that must be installed separately and be compatible with your GPU. Installing `cuda-python` via pip only provides the Python bindings.fixEnsure you have the appropriate NVIDIA GPU drivers and a compatible CUDA Toolkit installed on your system. Refer to NVIDIA's documentation for installation instructions.
affects: All versions
gotchaCompatibility between `cuda-python` package version and the system's CUDA Toolkit version is crucial. While minor version mismatches might work, major version mismatches (e.g., `cuda-python==12.x` with CUDA Toolkit 11.x) are likely to cause `ImportError` or runtime errors.fixTry to align the `cuda-python` package's major version with your installed CUDA Toolkit's major version (e.g., `pip install cuda-python==12.x`). Check the `cuda-python` documentation for recommended compatibility matrix.
affects: All versions
gotchaThe library exposes multiple API interfaces (e.g., `cuda.cuda_driver` for Driver API, `cuda.cuda_runtime` or `from cuda import cudart` for Runtime API). Choosing the correct API for your specific task (e.g., low-level control vs. higher-level abstractions, or integration with other libraries like Numba/PyTorch) is important.fixConsult the official `cuda-python` documentation to understand the differences between the Driver and Runtime APIs and select the interface best suited for your application.
affects: All versions
gotchaWhen using the low-level CUDA Driver API (`cuda.cuda_driver`), memory allocation and deallocation on the GPU (e.g., `drv.cuMemAlloc`, `drv.cuMemFree`) must be managed manually. Forgetting to free allocated memory can lead to GPU memory leaks and resource exhaustion.fixAlways pair `drv.cuMemAlloc` with a corresponding `drv.cuMemFree` call, ideally within a `try...finally` block or by using context managers if available for robust resource management.
affects: All versions
breakingThe `cuda-python` package must be installed in your Python environment to be imported. A `ModuleNotFoundError` indicates that the package (or a specific submodule like `cuda.cuda_driver`) could not be found.fixEnsure the `cuda-python` package is installed in your Python environment. You can typically install it using `pip install cuda-python` (or `pip install cuda-python==X.Y.Z` for a specific version compatible with your CUDA Toolkit).
affects: All versions
breakingInstallation of `cuda-python` may fail with `pip.ERROR: ResolutionImpossible` due to conflicting dependencies declared within the package's metadata or with other packages in the installation environment (e.g., Python 3.13 on Alpine Linux). This prevents `pip` from successfully resolving and installing a compatible set of dependencies for the requested `cuda-python` versions.fixInspect the full `pip` error output to identify the specific dependency conflicts. Try installing a known-compatible, specific version of `cuda-python` (e.g., `pip install cuda-python==X.Y.Z`). Consider using a different Python version or a less constrained environment (e.g., a standard glibc-based distribution like Ubuntu) if conflicts persist, as environment-specific packages or base libraries can sometimes interfere with dependency resolution.
affects: Multiple versions (as listed in the pip error output, e.g., 11.x, 12.x, 13.x), particularly in specific environments like Alpine Linux.
Upgrade
Version history
13.3.1latest on PyPI · released May 29, 2026
Audit
Dependencies
No dependency data recorded yet.