Registry / ai-ml / nvidia-nvtx-cu12

nvidia-nvtx-cu12

library12.9.79pypypi✓ verified 47d ago

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.

ai-ml observability data

pip install nvidia-nvtx-cu12

package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v12.9.79 · 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

glibc

py 3.10

✕ build_error

4/5 runs

py 3.11

✕ build_error

4/5 runs

py 3.12

✕ build_error

4/5 runs

py 3.13

✕ build_error

4/5 runs

py 3.9

✕ build_error

4/5 runs

Code

Verified usage

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

nvtx

✓ from nvidia import nvtx

✗ import nvtx

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.

import time import nvtx @nvtx.annotate("my_outer_function", color="blue") def my_function_to_profile(): time.sleep(0.05) # Simulate some work with nvtx.annotate("inner_loop_work", color="red"): for i in range(2): time.sleep(0.02) # More work nvtx.mark(f"Iteration {i} complete", color="green") if __name__ == "__main__": print("Running annotated code...") my_function_to_profile() print("Code finished. To profile this, save as e.g., 'demo.py' and run:\nnsys profile python demo.py") print("Then open the generated .qdrep file in NVIDIA Nsight Systems for visualization.")

Debug

Known issues

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

fix

Before creating any Pool objects or starting new processes, add: `import multiprocessing; multiprocessing.set_start_method("spawn", force=True)`

affects: All versions

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

fix

Disable `seccomp` restrictions for the profiled application if possible, or use non-injection based profiling features within Nsight Systems.

affects: All versions

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

fix

Ensure all components of your application are compiled and linked against a consistent NVTX and CUDA Toolkit version. Recompile dependent libraries if necessary.

affects: Potentially when migrating between CUDA Toolkit major versions (e.g., 11.x to 12.x)

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

fix

Use automatic annotation judiciously. For general profiling, prefer manual annotation with `@nvtx.annotate` or `with nvtx.annotate` on critical code sections.

affects: All versions

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

fix

Minimize the number of distinct `nvtx.Domain` objects created. Leverage `category` arguments for detailed event classification within a single domain.

affects: All versions

breakingThe `nvtx` Python module is not found, likely because the package has not been installed in the current environment.

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

affects: All versions

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

fix

To install this package, first ensure the NVIDIA Python Package Index is configured by installing `nvidia-pyindex`, then proceed with the package installation:
```
$ pip install nvidia-pyindex
$ pip install nvidia-nvtx-cu12
```

affects: All versions of `nvidia-nvtx-cu12` and similar NVIDIA packages hosted on the NVIDIA PyPI.

Upgrade

Version history

12.9.79latest on PyPI

Audit

Dependencies

NVIDIA CUDA Toolkit 12.xrequiredRequired for NVTX functionality and profiling with NVIDIA tools like Nsight Systems.

Agent activity

46 hits · last 30 days

node

ahrefsbot

seranking-bot

Resources

packagehttps://pypi.org/project/nvidia-nvtx-cu12/ ↗

homepagehttps://developer.nvidia.com/cuda-zone ↗