{"id":668,"library":"nvidia-nvtx-cu12","title":"NVIDIA Tools Extension (NVTX) Python Binding","description":"NVTX (NVIDIA Tools Extension SDK) is a C-based API with Python wrappers for annotating application code with events, ranges, and resources. These annotations provide contextual information for NVIDIA developer tools like Nsight Systems and Nsight Compute, enabling visual profiling and performance analysis of CPU and GPU activities in Python applications. The `nvidia-nvtx-cu12` package provides bindings specifically for CUDA 12.x environments. It is actively maintained with frequent updates, often tied to CUDA toolkit releases.","status":"active","version":"12.9.79","language":"python","source_language":"en","source_url":"https://github.com/NVIDIA/NVTX","tags":["nvidia","cuda","profiling","nvtx","performance","gpu","developer-tools"],"install":[{"cmd":"pip install nvidia-nvtx-cu12","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for NVTX functionality and profiling with NVIDIA tools like Nsight Systems.","package":"NVIDIA CUDA Toolkit 12.x","optional":false}],"imports":[{"wrong":"import nvtx","symbol":"nvtx","correct":"from nvidia import nvtx"}],"quickstart":{"code":"import time\nimport nvtx\n\n@nvtx.annotate(\"my_outer_function\", color=\"blue\")\ndef my_function_to_profile():\n    time.sleep(0.05) # Simulate some work\n    with nvtx.annotate(\"inner_loop_work\", color=\"red\"):\n        for i in range(2):\n            time.sleep(0.02) # More work\n            nvtx.mark(f\"Iteration {i} complete\", color=\"green\")\n\nif __name__ == \"__main__\":\n    print(\"Running annotated code...\")\n    my_function_to_profile()\n    print(\"Code finished. To profile this, save as e.g., 'demo.py' and run:\\nnsys profile python demo.py\")\n    print(\"Then open the generated .qdrep file in NVIDIA Nsight Systems for visualization.\")","lang":"python","description":"This example demonstrates how to use `nvtx.annotate` as a decorator for functions and as a context manager for code blocks, and `nvtx.mark` for instantaneous events. The annotated code itself does not directly produce a visible output, but generates profiling data that can be captured and visualized by NVIDIA Nsight Systems."},"warnings":[{"fix":"Before creating any Pool objects or starting new processes, add: `import multiprocessing; multiprocessing.set_start_method(\"spawn\", force=True)`","message":"When using NVTX with Python's `multiprocessing` module on Linux, the default `fork` start method can interfere with Nsight Systems' ability to inject and collect NVTX traces reliably. It is recommended to explicitly set the start method to `spawn`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Disable `seccomp` restrictions for the profiled application if possible, or use non-injection based profiling features within Nsight Systems.","message":"Nsight Systems trace features, including NVTX collection via process injection, may fail or cause instability in applications that use `seccomp` to restrict system calls. This can lead to process termination or hung applications.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all components of your application are compiled and linked against a consistent NVTX and CUDA Toolkit version. Recompile dependent libraries if necessary.","message":"Changes in the underlying NVTX C API between major CUDA Toolkit versions (e.g., CUDA 11.x to 12.x) can lead to compilation issues or runtime incompatibilities for other libraries that directly interface with NVTX's C API. While `nvidia-nvtx-cu12` is built for CUDA 12, users integrating multiple components should ensure NVTX version consistency.","severity":"breaking","affected_versions":"Potentially when migrating between CUDA Toolkit major versions (e.g., 11.x to 12.x)"},{"fix":"Use automatic annotation judiciously. For general profiling, prefer manual annotation with `@nvtx.annotate` or `with nvtx.annotate` on critical code sections.","message":"The `nvtx` library offers functionality for automatic annotation of all function calls. However, enabling this feature introduces significant performance overhead (potentially slowing down execution by more than 10x) and should be used cautiously for targeted debugging, not general profiling.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Minimize the number of distinct `nvtx.Domain` objects created. Leverage `category` arguments for detailed event classification within a single domain.","message":"Creating NVTX domains can be a relatively expensive operation. For optimal performance and clearer visualization, it is recommended to create a limited number of domains (e.g., one per major library or subsystem) and use categories for finer-grained grouping of events within those domains.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the 'nvtx' Python package. For CUDA-accelerated NVTX, install `nvidia-nvtx-cuXX` (replacing XX with your CUDA major version, e.g., `pip install nvidia-nvtx-cu12`). For a generic CPU-only version, install `nvtx-plugins-py` (`pip install nvtx-plugins-py`).","message":"The `nvtx` Python module is not found, likely because the package has not been installed in the current environment.","severity":"breaking","affected_versions":"All versions"},{"fix":"To install this package, first ensure the NVIDIA Python Package Index is configured by installing `nvidia-pyindex`, then proceed with the package installation:\n```\n$ pip install nvidia-pyindex\n$ pip install nvidia-nvtx-cu12\n```","message":"The `nvidia-nvtx-cu12` package, along with other NVIDIA Python packages, is hosted on the NVIDIA Python Package Index, not directly on PyPI.org. Attempting to install it directly via `pip install nvidia-nvtx-cu12` without configuring the NVIDIA index will result in a 'placeholder project' error, preventing installation.","severity":"breaking","affected_versions":"All versions of `nvidia-nvtx-cu12` and similar NVIDIA packages hosted on the NVIDIA PyPI."}],"env_vars":null,"search_vec":"'12':70 'activ':55,75 'analysi':50 'annot':22,31 'api':17 'applic':23,58 'base':16 'bind':6,66 'c':15 'c-base':14 'code':24 'comput':44 'contextu':33 'cpu':52 'cu12':63 'cuda':69,83,87 'develop':37,93 'developer-tool':92 'enabl':45 'environ':72 'event':26 'extens':3,10 'frequent':78 'gpu':54,91 'inform':34 'like':39 'maintain':76 'nsight':40,43 'nvidia':1,8,36,61,86 'nvidia-nvtx-cu12':60 'nvtx':4,7,62,89 'often':80 'packag':64 'perform':49,90 'profil':47,88 'provid':32,65 'python':5,19,57 'rang':27 'releas':85 'resourc':29 'sdk':11 'specif':67 'system':41 'tie':81 'tool':2,9,38,94 'toolkit':84 'updat':79 'visual':46 'wrapper':20 'x':71","created_at":"2026-03-28T17:09:41.619831+00:00","updated_at":"2026-04-16T17:29:54.447186+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"12.9.79","cli_name":"","cli_version":null,"type":"library","homepage":"https://developer.nvidia.com/cuda-zone","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/nvidia-nvtx-cu12/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","observability","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":"stale"}}