{"id":5672,"library":"nvidia-nvtx","title":"NVIDIA NVTX (NVIDIA Tools Extension Library)","description":"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.","status":"active","version":"13.2.20","language":"en","source_language":"en","source_url":"https://github.com/NVIDIA/NVTX","tags":["profiling","nvidia","gpu","performance","developer tools"],"install":[{"cmd":"pip install nvidia-nvtx","lang":"bash","label":"Install core NVIDIA NVTX library"},{"cmd":"pip install nvtx","lang":"bash","label":"Install Python bindings for NVTX"}],"dependencies":[{"reason":"Provides the Python API bindings for NVTX. Users typically install this package for Python-based profiling.","package":"nvtx","optional":false}],"imports":[{"note":"The Python API is provided by the `nvtx` package, not directly by `nvidia-nvtx`.","symbol":"nvtx","correct":"import nvtx"},{"symbol":"annotate","correct":"from nvtx import annotate"}],"quickstart":{"code":"import time\nimport nvtx\n\n@nvtx.annotate(color=\"blue\", message=\"my_function_range\")\ndef my_function():\n    for i in range(3):\n        with nvtx.annotate(f\"my_loop_iteration_{i}\", color=\"red\"):\n            time.sleep(0.01 * i)\n\nif __name__ == \"__main__\":\n    print(\"Running annotated function...\")\n    my_function()\n    print(\"Function complete. Use NVIDIA Nsight Systems to view profile (e.g., nsys profile -t nvtx python your_script.py)\")","lang":"python","description":"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`)."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your annotated Python script using `nsys profile -t nvtx python your_script.py` (or similar command for your chosen NVIDIA profiling tool).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Replace `pip install nvidia-nvtx-cuXX` with `pip install nvidia-nvtx` and `pip install nvtx`.","message":"Specialized `nvidia-nvtx-cuXX` packages (e.g., `nvidia-nvtx-cu13`) are deprecated. Users should migrate to using the main `nvidia-nvtx` and `nvtx` packages.","severity":"deprecated","affected_versions":"< 0.0.1 for `nvidia-nvtx-cu13` and similar"},{"fix":"Upgrade the `nvtx` Python package to version 0.2.13 or newer (`pip install --upgrade nvtx`).","message":"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.","severity":"gotcha","affected_versions":"nvtx < 0.2.13"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}