Install & Compatibility
Where this runs
tested against v12.9.79 · 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.915 runs
build_error
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 5.2s · import 0.000s · 61MB
59MB installed
● package 59MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cupti
✓ import nvidia.cupti
✗ from nvidia.cupti import cupti
This quickstart demonstrates how to use `cupti-python` to profile a simple Numba CUDA kernel. It registers callbacks to capture kernel launch information and then flushes the collected activities. Ensure you have `numba-cuda` and a CUDA-capable GPU with appropriate drivers installed. This code assumes `cupti-python` is installed and the `libcupti.so` library (provided by `nvidia-cuda-cupti-cu12`) is discoverable.
import numpy as np
from numba import cuda
from cupti import cupti
@cuda.jit
def vector_add(A, B, C):
idx = cuda.grid(1)
if idx < A.size:
C[idx] = A[idx] + B[idx]
def func_buffer_requested():
buffer_size = 8 * 1024 * 1024 # 8MB buffer
max_num_records = 0
return buffer_size, max_num_records
def func_buffer_completed(activities: list):
for activity in activities:
if activity.kind == cupti.ActivityKind.CONCURRENT_KERNEL:
print(f"Kernel Name: {activity.name}")
print(f"Kernel Duration (ns): {activity.end - activity.start}")
# Initialize data
vector_length = 1024 * 1024
A = np.random.rand(vector_length)
B = np.random.rand(vector_length)
C = np.zeros_like(A)
threads_per_block = 128
blocks_per_grid = (vector_length + (threads_per_block - 1)) // threads_per_block
# Register CUPTI callbacks
cupti.activity_register_callbacks(func_buffer_requested, func_buffer_completed)
# Enable CUPTI activity collection for concurrent kernels
cupti.activity_enable(cupti.ActivityKind.CONCURRENT_KERNEL)
# Launch kernel
vector_add[blocks_per_grid, threads_per_block](A, B, C)
cuda.synchronize()
# Flush and disable CUPTI activity
cupti.activity_flush()
cupti.activity_disable(cupti.ActivityKind.CONCURRENT_KERNEL)
Debug
Known issues
gotchaThe `nvidia-cuda-cupti-cu12` package provides the underlying C/C++ libraries. For Python-level interaction and APIs, the `cupti-python` package must also be installed. Direct Python imports are typically from `cupti` (the `cupti-python` module), not `nvidia_cuda_cupti_cu12`.fixInstall `cupti-python` alongside `nvidia-cuda-cupti-cu12` using `pip install cupti-python`.
affects: All versions
gotchaCUPTI Python relies on the `libcupti.so` C library. If `nvidia-cuda-cupti-cu12` is uninstalled or if `libcupti.so` cannot be found automatically, you may need to explicitly set the `LD_LIBRARY_PATH` environment variable to the directory containing `libcupti.so` (e.g., `$CUDA_TOOLKIT_INSTALL_PATH/extras/CUPTI/lib64`).fixEnsure `nvidia-cuda-cupti-cu12` is installed or set `export LD_LIBRARY_PATH=$CUDA_TOOLKIT_INSTALL_PATH/extras/CUPTI/lib64` before running CUPTI Python applications.
affects: All versions
breakingIn CUDA Toolkit 12.0, the activity record `CUpti_ActivityKernel8` was deprecated and replaced by `CUpti_ActivityKernel9` to accommodate new fields for devices with compute capability 9.0 and higher. This impacts users interacting with the low-level CUPTI C API, and potentially `cupti-python` users working with older code that explicitly references these activity kinds.fixUpdate profiling tools and code to use `CUpti_ActivityKernel9` where appropriate. Review CUPTI release notes for specific migration details.
affects: CUDA Toolkit 12.0 and later (corresponds to `nvidia-cuda-cupti-cu12` versions aligned with CUDA 12.0+)
gotchaOlder versions of `nvidia-cuda-cupti-cu12` (e.g., 12.4.127, 12.3.101) have been flagged with severe vulnerabilities. While the current version 12.9.79 should address these, always ensure you are running the latest stable version and keep your CUDA Toolkit and drivers updated.fixAlways use the latest version of `nvidia-cuda-cupti-cu12` and ensure your CUDA Toolkit installation and GPU drivers are up-to-date.
affects: <12.9.79
breakingThe script attempts to import 'numba' but it is not installed. 'numba' is a separate Python package and must be explicitly installed if your application depends on it.fixInstall 'numba' using pip: `pip install numba`.
affects: All versions
breakingThe `nvidia-cuda-cupti-cu12` package is hosted on the NVIDIA Python Package Index, not directly on PyPI. Attempting to install it directly via `pip install` without configuring the NVIDIA index will lead to a 'placeholder project' error during installation.fixFirst, install `nvidia-pyindex` using `pip install nvidia-pyindex` to configure pip to use the NVIDIA index. Then, install `nvidia-cuda-cupti-cu12`.
affects: All versions
Upgrade
Version history
12.9.79latest on PyPI · released Jun 5, 2025
Audit
Dependencies
cupti-pythonrequiredProvides Python APIs for interacting with CUPTI functionality; `nvidia-cuda-cupti-cu12` supplies the underlying C library.
numba-cudaoptionalOften used in examples and for just-in-time compilation of CUDA kernels in Python for profiling.
cuda-pythonoptionalProvides CUDA Python Driver APIs, used in some advanced CUPTI Python samples.