nvtx

library0.2.16pypypi✓ verified 22d ago

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.

observability devops

pip install nvtx

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · NVTX

nvtx

observabilitypythonv0.2.16

Install

1.8s avg

Import

64ms

Disk

26MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.16 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.064s · 28MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nvtx

✓ import nvtx

annotate

✓ @nvtx.annotate()

Can be used as a decorator or context manager for code ranges.

mark

✓ nvtx.mark(message="Event")

For instantaneous events.

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.

import time import nvtx import os # Define a function to be annotated @nvtx.annotate(color="blue") def my_function(): for i in range(os.environ.get('NVTX_ITERATIONS', 2)): with nvtx.annotate(f"my_loop_iteration_{i}", color="red"): time.sleep(0.1) if __name__ == "__main__": print("Running annotated code...") my_function() print("Code execution complete. Profile with NVIDIA Nsight Systems.") # To profile, run from your terminal: # nsys profile -t nvtx python your_script_name.py # Then open the generated .qdrep file in Nsight Systems GUI.

Debug

Known issues

gotchaIn `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.

fix

Upgrade to `nvtx` 0.2.13 or newer. Ensure proper exception handling if using older versions.

affects: <0.2.13

gotchaTo 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.

fix

Set `export NVTX_DISABLE=1` in your shell before running your Python script.

affects: All versions

gotchaWhen 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.

fix

Use `multiprocessing.set_start_method('spawn', force=True)` or `get_context('spawn').Pool()` for multiprocessing.

affects: All versions (on Linux with multiprocessing.fork)

gotchaUsing 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.

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.

affects: All versions

gotchaNVTX 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.

fix

Organize annotations with a minimal number of domains and leverage categories for further sub-grouping.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'nvtx'

The 'nvtx' Python package is not installed in the current Python environment.

fix

Install the package using pip: `python -m pip install nvtx` or conda: `conda install -c conda-forge nvtx`.

RuntimeError: NVTX functions not installed. Are you sure you have a CUDA build?

This error occurs when using NVTX functionality, particularly via `torch.cuda.nvtx`, on a system without a properly configured CUDA environment or a compatible NVIDIA GPU, even if the `nvtx` Python package is installed.

fix

Ensure a CUDA-enabled PyTorch is installed and running on a system with a compatible NVIDIA GPU and drivers. If running on a CPU-only system, avoid using `torch.cuda.nvtx` specific calls and use the generic `nvtx` package for CPU-side annotations if desired.

AttributeError: module 'nvtx' has no attribute 'range'

The user is attempting to call `nvtx.range()` directly. The `nvtx` Python library provides range annotation functionality primarily through `nvtx.annotate` (as a decorator or context manager) or explicit `nvtx.start_range()` and `nvtx.end_range()` calls.

fix

Use `@nvtx.annotate(message='my_range')` as a decorator, `with nvtx.annotate(message='my_range'):` as a context manager, or `range_id = nvtx.start_range(message='my_range'); nvtx.end_range(range_id)` for explicit range management.

TypeError: mark() missing 1 required positional argument: 'message'

The `nvtx.mark()` function requires at least one positional argument, `message`, to describe the instantaneous event being marked.

fix

Provide a string message when calling `nvtx.mark()`, e.g., `nvtx.mark(message='My event message')`.

Upgrade

Version history

0.2.16latest on PyPI · released Aug 12, 2026

Audit

Dependencies

pythonrequiredRequired for the Python bindings.

numpyoptionalRequired for NVTX event payloads of types other than int or float.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/NVIDIA/NVTX ↗

packagehttps://pypi.org/project/nvtx/ ↗

homepagehttps://nvidia.github.io/NVTX/ ↗

docshttps://nvidia.github.io/NVTX/python/ ↗