cuda_bindings_12

cuda.bindings: Low-level CUDA interfaces

cuda.bindings is a standard set of low-level interfaces, providing full coverage of and access to the CUDA host APIs from Python. Checkout the Overview page for the workflow and performance results.

Installing

Please refer to the Installation page for instructions and required/optional dependencies.

Developing

Follow the repository contribution guide and the shared regeneration and review guidance for source builds and cross-major changes.

CUDA 12.9 sources are developed here on main. This root and cuda_bindings_13/ build the same distribution and Python namespace; use separate environments for them. From the repository root:

pixi run --manifest-path cuda_bindings_12 -e cu12 test

This builds bindings and Cython test extensions from source, then runs the GPU test suite. pixi run -e cu12 test-bindings selects the same package. For an existing Python environment with CUDA 12.9 headers, a compiler, and pip 25.1 or newer:

cd cuda_bindings_12
python -m pip install -v -e . --group test
tests/cython/build_tests.sh
python -m pytest tests/ tests/cython/

Use build_tests.bat on Windows. Free-threaded Python also needs the test-ft dependency group.

Versions follow reachable v12.* tags through standard setuptools-scm. Source builds need the matching tag and the history connecting it to the checkout. See the repository's version lifecycle.

Testing

Run the commands below from cuda_bindings_12/, in an environment containing the CUDA 12 bindings. With pip 25.1 or newer, install the package and its test dependency group with python -m pip install -v -e . --group test.

Multiple testing options are available:

• Python Unit Tests
• Cython Unit Tests
• Samples
• Benchmark

Python Unit Tests

Responsible for validating different binding usage patterns. Unit test test_kernelParams.py is particularly special since it demonstrates various approaches in setting up kernel launch parameters.

To run these tests:

• python -m pytest tests/ against editable installations
• pytest tests/ against installed packages

Cython Unit Tests

Cython tests are located in tests/cython and need to be built. These builds have the same CUDA Toolkit header requirements as Installing from Source where the major.minor version must match cuda.bindings. To build them:

1. Setup environment variable CUDA_HOME with the path to the CUDA Toolkit installation.
2. Run the build_tests script located in tests/cython appropriate to your platform. This will both cythonize the tests and build them.

To run these tests:

• python -m pytest tests/cython/ against editable installations
• pytest tests/cython/ against installed packages

Samples

Running the samples requires CUDA 12 NVRTC, supplied by the CUDA Toolkit or nvidia-cuda-nvrtc-cu12. The test dependency group does not install it.

Various CUDA Samples that were rewritten using CUDA Python are located in examples.

In addition, extra examples are included:

• examples/extra/jit_program_test.py: Demonstrates the use of the API to compile and launch a kernel on the device. Includes device memory allocation / deallocation, transfers between host and device, creation and usage of streams, and context management.
• examples/extra/numba_emm_plugin.py: Implements a Numba External Memory Management plugin, showing that this CUDA Python Driver API can coexist with other wrappers of the driver API.

To run these samples:

• python -m pytest examples/ against editable installations
• pytest examples/ against installed packages

Benchmark

See the shared cuda.bindings benchmark harness for performance benchmarks and usage instructions. Its configured environments currently target CUDA 13; benchmarking CUDA 12 requires a compatible environment configured separately.