NVIDIA NVTX (NVIDIA Tools Extension Library)

13.2.20 · active · verified Thu Apr 09

NVIDIA Tools Extension (NVTX) is a C-based API for annotating events, code ranges, and resources within applications, allowing developers to visualize and analyze performance using NVIDIA profiling tools like Nsight Systems. While `nvidia-nvtx` (version 13.2.20) provides the core C API, Python users typically interact with NVTX through the separate `nvtx` Python package (current version 0.2.15), which offers native Python wrappers for a subset of the C API. It enables profiling Python code, including CPU and GPU activities, and visualizing these on a timeline.

Warnings

gotcha The `nvidia-nvtx` PyPI package provides the underlying C-based NVTX library. For Python-level annotations, you primarily use the `nvtx` PyPI package. Ensure you install `nvtx` (via `pip install nvtx`) to access the Python API.
Fix: Install `nvtx` via `pip install nvtx` in your Python environment. The `nvidia-nvtx` package may still be a necessary low-level dependency depending on your system setup.
gotcha NVTX API calls, by default, do nothing on their own. To collect and visualize profiling data, your application must be launched under an NVIDIA developer tool, such as NVIDIA Nsight Systems. Without such a tool, NVTX annotations will not yield any profiling output.
Fix: Run your annotated Python script using `nsys profile -t nvtx python your_script.py` (or similar command for your chosen NVIDIA profiling tool).
deprecated Specialized `nvidia-nvtx-cuXX` packages (e.g., `nvidia-nvtx-cu13`) are deprecated. Users should migrate to using the main `nvidia-nvtx` and `nvtx` packages.
Fix: Replace `pip install nvidia-nvtx-cuXX` with `pip install nvidia-nvtx` and `pip install nvtx`.
gotcha In earlier versions of the `nvtx` Python package (prior to 0.2.13), decorator ranges might not end correctly if an exception was thrown within the decorated function. This could lead to incomplete or misleading profiling data.
Fix: Upgrade the `nvtx` Python package to version 0.2.13 or newer (`pip install --upgrade nvtx`).

Install

pip install nvidia-nvtx Install core NVIDIA NVTX library
pip install nvtx Install Python bindings for NVTX

Imports

nvtx
```
import nvtx
```
The Python API is provided by the `nvtx` package, not directly by `nvidia-nvtx`.
annotate
```
from nvtx import annotate
```

Quickstart

This example demonstrates how to annotate Python code using the `nvtx` package. The `@nvtx.annotate` decorator and `with nvtx.annotate` context manager create profiled ranges. To collect and visualize this data, you need to run your script with an NVIDIA profiling tool, such as NVIDIA Nsight Systems (e.g., `nsys profile -t nvtx python your_script.py`).

import time
import nvtx

@nvtx.annotate(color="blue", message="my_function_range")
def my_function():
    for i in range(3):
        with nvtx.annotate(f"my_loop_iteration_{i}", color="red"):
            time.sleep(0.01 * i)

if __name__ == "__main__":
    print("Running annotated function...")
    my_function()
    print("Function complete. Use NVIDIA Nsight Systems to view profile (e.g., nsys profile -t nvtx python your_script.py)")

view raw JSON →