{"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":"python","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":[{"wrong":"from cupy_cupti import profiler","symbol":"cupti","correct":"import cupti"},{"symbol":"profiler_host","correct":"from cupti import profiler_host"},{"symbol":"callback_wrappers","correct":"from cupti import callback_wrappers"}],"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,"search_vec":"'13.2.0':79 'access':41 'align':81 'also':49 'api':46 'applic':36 'bind':12 'c':26,45 'cuda':16,35,86,89 'cupti':2,7,20,43,93 'cupti-python':6 'cupy_cupti.profiler':59 'current':76 'deep':94 'depend':51 'detail':30 'direct':40 'distribut':66 'enabl':29 'expos':22 'function':27 'gpu':92 'higher':54 'higher-level':53 'instrument':31 'interfac':19 'learn':95 'level':25,55 'librari':4,9 'like':58 'low':24 'low-level':23 'major':85 'nvidia':1,15,91 'offer':39 'part':62 'perform':96 'profil':17,33,56,72,90 'provid':10 'python':3,8,11 'releas':83 'session':73 'simplifi':68 'start':69 'stop':71 'tool':18,57 'toolkit':87 'version':78,88","created_at":"2026-04-16T18:47:32.039897+00:00","updated_at":"2026-04-16T18:47:32.039897+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"13.3.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":"https://docs.nvidia.com/cupti-python/13.2.0/index.html","changelog":null,"pypi":"https://pypi.org/project/cupti-python/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","observability","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}