{"id":8919,"library":"cupti-python","title":"NVIDIA CUPTI Python Library","description":"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.","status":"active","version":"13.2.0","language":"en","source_language":"en","source_url":"https://github.com/NVIDIA/cupti-python","tags":["cuda","profiling","nvidia","gpu","cupti","deep learning","performance"],"install":[{"cmd":"pip install cupti-python","lang":"bash","label":"Install latest version"},{"cmd":"pip install cupti-python==13.2.0","lang":"bash","label":"Install specific version"}],"dependencies":[{"reason":"Required for higher-level CUDA operations and the quickstart example using `cupy_cupti.profiler` for meaningful GPU activity.","package":"cupy","optional":true}],"imports":[{"note":"The PyPI package `cupti-python` installs the Python package `cupy_cupti`, which contains the `profiler` module for higher-level control.","wrong":"from cupti_python import profiler","symbol":"profiler","correct":"from cupy_cupti import profiler"}],"quickstart":{"code":"import os\nimport cupy_cupti.profiler as cupti_profiler\nimport cupy as cp\nimport sys\n\n# This quickstart demonstrates starting and stopping CUPTI profiling.\n# Actual profiling data collection (e.g., via callbacks or external tools)\n# is beyond the scope of this basic example and typically requires tools like Nsight Systems.\n\nif not cp.cuda.is_available():\n    print(\"CUDA is not available. Cannot run CUPTI profiling example.\")\n    sys.exit(1)\nelse:\n    print(\"CUPTI Profiling Quickstart (requires CuPy installed):\")\n    print(\"--------------------------------------------------\")\n    \n    # Define a simple CuPy operation to profile\n    def run_cuda_kernel():\n        a = cp.random.rand(100, 100).astype(cp.float32)\n        b = cp.random.rand(100, 100).astype(cp.float32)\n        c = a @ b\n        cp.cuda.Stream.null.synchronize() # Ensure ops complete before profiler stops\n        print(f\"Executed a CuPy matrix multiplication. Result shape: {c.shape}\")\n\n    try:\n        print(\"Starting CUPTI profiler...\")\n        cupti_profiler.start()\n\n        run_cuda_kernel()\n\n        cupti_profiler.stop()\n        print(\"CUPTI profiler stopped.\")\n        print(\"\\nNote: For actual profile data, you would typically integrate with NVIDIA Nsight Systems \")\n        print(\"or set up CUPTI callbacks using the lower-level API. This script only marks a profiling region.\")\n    except Exception as e:\n        print(f\"An error occurred during profiling: {e}\")\n        print(\"Ensure CUPTI libraries are discoverable (e.g., via LD_LIBRARY_PATH) and CUDA is properly set up.\")","lang":"python","description":"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."},"warnings":[{"fix":"Always use `from cupy_cupti import ...` for imports.","message":"The 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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"CUPTI 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.","severity":"breaking","affected_versions":"All versions, especially when upgrading CUDA Toolkit"},{"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.","message":"`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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your `cupti-python` applications on a Linux system with a compatible NVIDIA GPU and CUDA Toolkit installation.","message":"The NVIDIA CUPTI library, and by extension `cupti-python`, is primarily supported on Linux operating systems. Windows support is generally not available or highly experimental.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement from `import cupti_python` to `import cupy_cupti`.","cause":"The PyPI package `cupti-python` installs a Python package named `cupy_cupti`, not `cupti_python`.","error":"ModuleNotFoundError: No module named 'cupti_python'"},{"fix":"Verify that the CUDA Toolkit is installed and its `lib64` directory (e.g., `/usr/local/cuda/lib64`) is correctly added to your `LD_LIBRARY_PATH` environment variable (on Linux). For example: `export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH`.","cause":"The NVIDIA CUPTI shared library (`libcupti.so`) is not found in the system's library search paths.","error":"OSError: libcupti.so: cannot open shared object file: No such file or directory"},{"fix":"Update your NVIDIA GPU drivers to a version compatible with your CUDA Toolkit, or install a CUDA Toolkit version that is compatible with your current drivers. Refer to NVIDIA's CUDA compatibility matrix.","cause":"There is a mismatch between your installed NVIDIA display driver and the CUDA Toolkit version being used by `cupti-python` (and any other CUDA-dependent libraries like CuPy).","error":"RuntimeError: CUDA driver version is insufficient for CUDA runtime version."},{"fix":"Execute your Python script by launching it with Nsight Systems: `nsys profile python your_script.py`. The `profiler.start()` and `stop()` calls will then serve to define specific regions within the Nsight Systems timeline.","cause":"While `start()` and `stop()` mark regions, Nsight Systems needs to launch and monitor the Python process directly to capture all profiling data and callbacks.","error":"Nsight Systems reports no GPU activity or missing CUPTI callbacks when using `cupy_cupti.profiler.start/stop`."}]}