{"id":4992,"library":"nvtx","title":"NVTX Python Bindings","description":"NVTX (NVIDIA Tools Extension Library) is a cross-platform API for annotating source code to provide contextual information to developer tools like NVIDIA Nsight Systems. The `nvtx` Python library provides native Python wrappers for a subset of the NVTX C API, enabling Python developers to mark events and define code ranges for profiling and visualization of CPU and GPU activities. The current Python package version is 0.2.15, with active development tied to the broader NVTX v3.x.x core library releases.","status":"active","version":"0.2.15","language":"en","source_language":"en","source_url":"https://github.com/NVIDIA/NVTX","tags":["nvidia","profiling","gpu","performance","tooling","nsight-systems","annotation"],"install":[{"cmd":"pip install nvtx","lang":"bash","label":"Pip"},{"cmd":"conda install -c conda-forge nvtx","lang":"bash","label":"Conda (preferred)"}],"dependencies":[{"reason":"Required for the Python bindings.","package":"python","version":">=3.6"},{"reason":"Required for NVTX event payloads of types other than int or float.","package":"numpy","optional":true}],"imports":[{"symbol":"nvtx","correct":"import nvtx"},{"note":"Can be used as a decorator or context manager for code ranges.","symbol":"annotate","correct":"@nvtx.annotate()"},{"note":"For instantaneous events.","symbol":"mark","correct":"nvtx.mark(message=\"Event\")"}],"quickstart":{"code":"import time\nimport nvtx\nimport os\n\n# Define a function to be annotated\n@nvtx.annotate(color=\"blue\")\ndef my_function():\n    for i in range(os.environ.get('NVTX_ITERATIONS', 2)):\n        with nvtx.annotate(f\"my_loop_iteration_{i}\", color=\"red\"):\n            time.sleep(0.1)\n\nif __name__ == \"__main__\":\n    print(\"Running annotated code...\")\n    my_function()\n    print(\"Code execution complete. Profile with NVIDIA Nsight Systems.\")\n    # To profile, run from your terminal:\n    # nsys profile -t nvtx python your_script_name.py\n    # Then open the generated .qdrep file in Nsight Systems GUI.","lang":"python","description":"This example demonstrates how to use `nvtx.annotate` as both a decorator for a function and a context manager for a code block. To observe these annotations, you typically run the Python script using NVIDIA Nsight Systems' command-line interface (`nsys profile`) and then visualize the generated `.qdrep` file in the Nsight Systems GUI."},"warnings":[{"fix":"Upgrade to `nvtx` 0.2.13 or newer. Ensure proper exception handling if using older versions.","message":"In `nvtx` versions prior to 0.2.13 (or NVTX core v3.2.2/v3.3.0), decorator ranges might not have ended correctly if an exception was thrown within the decorated function, potentially leading to incomplete or misleading profiles.","severity":"gotcha","affected_versions":"<0.2.13"},{"fix":"Set `export NVTX_DISABLE=1` in your shell before running your Python script.","message":"To disable NVTX annotations at runtime and reduce overhead, set the `NVTX_DISABLE` environment variable before launching your application. This can be crucial during performance-critical 'warmup' phases or when profiling is not desired.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `multiprocessing.set_start_method('spawn', force=True)` or `get_context('spawn').Pool()` for multiprocessing.","message":"When using Python's `multiprocessing` module on Linux with NVTX instrumentation, the default 'fork' start method can lead to issues with Nsight Systems' process injection. It is recommended to explicitly use the 'spawn' start method for correct profiling.","severity":"gotcha","affected_versions":"All versions (on Linux with multiprocessing.fork)"},{"fix":"Prefer `nvtx.annotate()` decorators or context managers for specific code regions, or `nvtx.mark()` for events, rather than global automatic annotation if overhead is a concern.","message":"Using automatic function annotation (e.g., via command-line interface or `nvtx.Profile` class) can introduce significant overhead (more than 10x) due to annotating every function invocation. Use it cautiously and prefer manual annotation for critical paths.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Organize annotations with a minimal number of domains and leverage categories for further sub-grouping.","message":"NVTX Domains are computationally expensive to create and should be used sparingly (e.g., one per library). For finer-grained grouping of annotations within a domain, use Categories, which are less expensive.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}