Registry / ai-ml / cupti-python

cupti-python

JSON →
library13.3.0pypypi✓ verified 87d ago

The `cupti-python` library provides Python bindings for the NVIDIA CUDA Profiling Tools Interface (CUPTI). It exposes low-level C functions to enable detailed instrumentation and profiling of CUDA applications. While it offers direct access to CUPTI's C API, it's also a dependency for higher-level profiling tools like `cupy_cupti.profiler` (which is part of the same distribution) that simplify starting and stopping profiling sessions. It is currently at version 13.2.0 and aligns its releases with major CUDA Toolkit versions.

pip install cupti-python
INSTALL
IMPORT
SIG · CUPTI-PYTHON
C
cupti-python
ai-mlpythonv13.3.0
Install
4.2s avg
Import
—
Disk
163MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v13.3.0 · 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
musl
glibc
py 3.10
✕ build_error
✓ 4.42s
py 3.11
✕ build_error
✓ 4.2s
py 3.12
✕ build_error
✓ 4.08s
py 3.13
✕ build_error
✓ 4.17s
py 3.9
✕ build_error
3/6 runs
163MB installed
● package 163MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cupti
✓ import cupti
✗ from cupy_cupti import profiler
profiler_host
✓ from cupti import profiler_host
callback_wrappers
✓ from cupti import callback_wrappers

This example demonstrates how to use `cupy_cupti.profiler` to start and stop a profiling session around a CuPy CUDA operation. It requires CuPy to be installed for meaningful GPU activity. Note that `start()` and `stop()` primarily mark regions; actual data collection usually involves external tools like Nsight Systems or custom CUPTI callbacks.

import os import cupy_cupti.profiler as cupti_profiler import cupy as cp import sys # This quickstart demonstrates starting and stopping CUPTI profiling. # Actual profiling data collection (e.g., via callbacks or external tools) # is beyond the scope of this basic example and typically requires tools like Nsight Systems. if not cp.cuda.is_available(): print("CUDA is not available. Cannot run CUPTI profiling example.") sys.exit(1) else: print("CUPTI Profiling Quickstart (requires CuPy installed):") print("--------------------------------------------------") # Define a simple CuPy operation to profile def run_cuda_kernel(): a = cp.random.rand(100, 100).astype(cp.float32) b = cp.random.rand(100, 100).astype(cp.float32) c = a @ b cp.cuda.Stream.null.synchronize() # Ensure ops complete before profiler stops print(f"Executed a CuPy matrix multiplication. Result shape: {c.shape}") try: print("Starting CUPTI profiler...") cupti_profiler.start() run_cuda_kernel() cupti_profiler.stop() print("CUPTI profiler stopped.") print("\nNote: For actual profile data, you would typically integrate with NVIDIA Nsight Systems ") print("or set up CUPTI callbacks using the lower-level API. This script only marks a profiling region.") except Exception as e: print(f"An error occurred during profiling: {e}") print("Ensure CUPTI libraries are discoverable (e.g., via LD_LIBRARY_PATH) and CUDA is properly set up.")
Debug
Known issues
gotchaThe PyPI package name is `cupti-python`, but the actual Python package name you import is `cupy_cupti`. Importing `cupti_python` directly will result in a `ModuleNotFoundError`.
fix
Always use `from cupy_cupti import ...` for imports.
affects: All versions
breakingCUPTI API can change significantly across major CUDA Toolkit versions. While `cupti-python` aims for compatibility, using a version that mismatches your installed CUDA Toolkit or NVIDIA drivers can lead to runtime errors or incorrect profiling data.
fix
Ensure your `cupti-python` version is compatible with your installed CUDA Toolkit and NVIDIA drivers. Check the official `cupti-python` GitHub for recommended compatibility matrices.
affects: All versions, especially when upgrading CUDA Toolkit
gotcha`libcupti.so` (the NVIDIA CUPTI shared library) must be discoverable by your system. If not found, you'll encounter `OSError: libcupti.so: cannot open shared object file`.
fix
Ensure the CUDA Toolkit's `lib64` directory (e.g., `/usr/local/cuda/lib64`) is included in your `LD_LIBRARY_PATH` environment variable on Linux.
affects: All versions
gotchaThe `cupy_cupti.profiler.start()` and `.stop()` methods primarily mark profiling regions. For comprehensive profiling data, you often need to run your Python script under an external profiling tool like NVIDIA Nsight Systems.
fix
If expecting full profiling reports, launch your Python script using Nsight Systems (e.g., `nsys profile python your_script.py`) instead of running it standalone.
affects: All versions
gotchaThe NVIDIA CUPTI library, and by extension `cupti-python`, is primarily supported on Linux operating systems. Windows support is generally not available or highly experimental.
fix
Run your `cupti-python` applications on a Linux system with a compatible NVIDIA GPU and CUDA Toolkit installation.
affects: All versions
Upgrade
Version history
13.3.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
cupyoptionalRequired for higher-level CUDA operations and the quickstart example using `cupy_cupti.profiler` for meaningful GPU activity.
Agent activity
33 hits · last 30 days
node
28
OpenAI (training)
1
Resources
cupti-python — pip install cupti-python · libregistry