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
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
No direct imports
✓ This package is a meta-package for C++/binary libraries and does not provide direct Python imports. Functionality is exposed via frameworks like PyTorch or TensorFlow.
Python libraries like PyTorch or JAX internally detect and utilize the CUDA libraries installed by `cuda-toolkit`.
Since `cuda-toolkit` itself has no Python API, a quickstart demonstrates how a common library like PyTorch leverages the installed CUDA libraries. This snippet checks for CUDA availability and prints device information.
import torch
if torch.cuda.is_available():
print(f"CUDA is available! Device name: {torch.cuda.get_device_name(0)}")
print(f"CUDA version: {torch.version.cuda}")
print(f"PyTorch CUDA version: {torch.cuda.get_device_capability(0)}")
else:
print("CUDA is NOT available. Check your NVIDIA drivers and cuda-toolkit installation.")
Debug
Known issues
gotchaThe `cuda-toolkit` PyPI package does NOT install NVIDIA GPU drivers. You must manually install compatible drivers from NVIDIA's website for your GPU before attempting to use CUDA.fixDownload and install the correct NVIDIA GPU drivers from the official NVIDIA website (e.g., `www.nvidia.com/drivers`).
affects: All versions
gotchaThis package is a meta-package for C++/binary libraries and does not provide direct Python imports. You interact with CUDA through deep learning frameworks (e.g., PyTorch, TensorFlow) or specialized libraries (e.g., Numba, JAX) that link against these installed binaries.fixTo use CUDA in Python, install a framework like `torch` or `tensorflow` (ensure you install their CUDA-enabled versions, e.g., `torch` often defaults to CPU if CUDA is not detected or installed correctly).
affects: All versions
breakingMajor CUDA version changes (e.g., from 11.x to 12.x) can introduce incompatibilities with existing deep learning frameworks. Frameworks like PyTorch or TensorFlow are typically built against specific CUDA versions and might not work correctly with significantly newer or older CUDA installations.fixAlways check the compatibility matrix of your deep learning framework (e.g., PyTorch, TensorFlow) with the desired CUDA version. You may need to upgrade or downgrade your framework or install a specific `cuda-toolkit` version (e.g., `cuda-toolkit==11.8.0`) to match.
affects: All major version changes
gotchaThe `pip install cuda-toolkit` primarily provides the runtime libraries. For full CUDA development (e.g., compiling custom CUDA kernels with `nvcc`), you may still need a full system-wide NVIDIA CUDA Toolkit installation from NVIDIA's developer site, which includes compilers, debuggers, and development headers.fixIf you need `nvcc` or other development tools, consider a full system installation of the NVIDIA CUDA Toolkit. Ensure its version is compatible with your PyPI `cuda-toolkit` installation.
affects: All versions
gotchaDespite `pip` installations, certain applications or older scripts might still rely on environment variables like `CUDA_HOME` or `LD_LIBRARY_PATH` to locate CUDA libraries. PyPI installations typically place libraries in Python's site-packages, which might not be on the system's default search paths for all tools.fixIf encountering 'CUDA not found' errors with non-Python tools or specific C++ extensions, try setting `CUDA_HOME` to the root of the PyPI installed CUDA (e.g., `~/.local/lib/pythonX.Y/site-packages/nvidia/cuda_toolkit/`) or manually adding the library paths to `LD_LIBRARY_PATH`.
affects: All versions
Upgrade
Version history
13.3.1latest on PyPI · released Jun 29, 2026
Audit
Dependencies
nvidia-cuda-runtimerequiredCore CUDA runtime libraries, pulled by the meta-package.
nvidia-cublas-cu13requiredcuBLAS library for linear algebra, versioned for CUDA 13.x.
nvidia-cudnn-cu13requiredcuDNN library for deep neural networks, versioned for CUDA 13.x.
NVIDIA GPUrequiredRequires compatible NVIDIA GPU hardware.
NVIDIA GPU DriversrequiredRequires pre-installed, compatible NVIDIA GPU drivers from NVIDIA's website.