Migrate nsight-python to use NCU's dynamic injection loading feature; 1.0.0 release updates (#48)

Signed-off-by: Alok Joshi <aljoshi@nvidia.com>

Author: Alok-Joshi

README.md

@@ -60,7 +60,3 @@ Review the [CONTRIBUTING.md](Contributing.md) file for information on how to con
 ## License
 
 All files hosted in this repository are subject to the [Apache 2.0](LICENSE) license.
-
-## Disclaimer
-
-nsight-python is in a Beta state. Beta products may not be fully functional, may contain errors or design flaws, and may be changed at any time without notice. We appreciate your feedback to improve and iterate on our Beta products.

docs/source/_static/switcher.json

@@ -3,6 +3,10 @@
     "version": "latest",
     "url": "https://docs.nvidia.com/nsight-python/"
   },
+  {
+    "version": "1.0.0",
+    "url": "https://docs.nvidia.com/nsight-python/1.0.0/"
+  },
   {
     "version": "0.9.6",
     "url": "https://docs.nvidia.com/nsight-python/0.9.6/"

docs/source/index.rst

@@ -28,7 +28,6 @@ Welcome to the Nsight Python documentation!
    release_notes/release_notes
    release_notes/known_issues
    release_notes/support
-   release_notes/disclaimer
 
 
 .. toctree::

docs/source/installation/runtime_requirements.rst

@@ -4,4 +4,15 @@
 Runtime Requirements
 =====================
 
-* **NVIDIA Nsight Compute from CUDA toolkit 12.0+**: nsight-python uses NVIDIA Nsight Compute CLI(ncu). Please make sure that ncu version 2022.4.0 or later is installed and available in the system path.
+* **NVIDIA Nsight Compute from CUDA Toolkit 13.3 Update 1 or later**: nsight-python uses the NVIDIA Nsight Compute CLI (ncu 2026.2.1+). Ensure ``ncu`` is installed and available on the system path.
+
+Import Ordering
+---------------
+
+``import nsight`` must come before:
+
+* **CUDA initialization**: You must import nsight before any operation that initializes CUDA (e.g. ``torch.cuda.init()``). If CUDA is initialized first, NVIDIA Nsight Compute cannot attach correctly and profiling fails (commonly with ``NV_INJ_ERROR_NOT_INITIALIZED``).
+
+  **Recommendation**: Place ``import nsight`` at the top of your script, before all CUDA-related imports and calls.
+
+* **Any NVTX API calls**: nsight-python updates ``NVTX_INJECTION64_PATH`` at import time. Any NVTX usage before ``import nsight`` will cause NVTX annotation ranges to be missed and profiling results to be incomplete.

docs/source/release_notes/disclaimer.rst

@@ -4,42 +4,6 @@
 Known Issues
 ============
 
-- Nsight Python launches the application python script again with NVIDIA Nsight Compute CLI (ncu) for each ``@nsight.analyze.kernel`` decorator.
-
-  - Due to this issue, using ``nsight-python`` in interactive notebook environments
-    (e.g., Jupyter Notebook or Google Colab) is not supported. Refer to
-    `GitHub issue #3 <https://github.com/NVIDIA/nsight-python/issues/3>`_
-    for more information..
-
-  In the meantime, you can use the following workaround by placing your benchmark
-  into a standalone Python script and executing it outside the interactive cell environment::
-
-      %%writefile quickstart.py
-      import torch
-      import nsight
-
-      @nsight.analyze.kernel
-      def benchmark_matmul(n):
-          """
-          The simplest possible benchmark.
-          We create two matrices and multiply them.
-          """
-          # Create two NxN matrices on GPU
-          a = torch.randn(n, n, device="cuda")
-          b = torch.randn(n, n, device="cuda")
-
-          # Mark the kernel we want to profile
-          with nsight.annotate("matmul"):
-              c = a @ b
-
-          return c
-
-      result = benchmark_matmul(1024)
-
-  Then run the script with::
-
-      %run quickstart.py
-
 - Kernels launched from a subprocess which is created within the annotated region will not be profiled.
 - For the ``nsight.analyze.kernel``'s ``replay_mode="range"`` option, only a subset of CUDA APIs are supported within the annotated range. If an unsupported API call is detected, an error will be reported. For details on supported APIs, refer to the `NVIDIA Nsight Compute Profiling Guide <https://docs.nvidia.com/nsight-compute/ProfilingGuide/index.html#supported-apis>`_. In such cases, you can either switch to ``replay_mode="kernel"`` or modify the code to exclude the unsupported API from the annotated range.
 - Nested annotations (using ``nsight.annotate`` within another ``nsight.annotate`` context) are not supported. nsight-python errors out when nested annotations are used.

docs/source/release_notes/known_issues.rst

@@ -7,5 +7,6 @@ Release Notes
 .. toctree::
    :maxdepth: 2
 
+   topics/updates-in-nsight-python-1.0.0
    topics/updates-in-nsight-python-0.9.6
    topics/updates-in-nsight-python-0.9.5

docs/source/release_notes/release_notes.rst

@@ -0,0 +1,70 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+Updates in Nsight Python 1.0.0
+==============================
+
+Enhancements
+------------
+
+- **Eliminated per-decorator Python script relaunch**: Previously, nsight-python
+  relaunched the entire Python script once for each :func:`@nsight.analyze.kernel <nsight.analyze.kernel>` decorated
+  function in order to collect profiles using NVIDIA Nsight Compute. nsight-python now
+  dynamically loads NVIDIA Nsight Compute's CUDA injection library at import time and uses
+  ``ncu --mode attach`` to attach to the running Python process, with no script relaunch.
+  This reduces profiling overhead and avoids relaunch-related side effects from
+  re-running module/import-time code.
+  Interactive environments such as Jupyter Notebook and Google Colab are now supported
+  (fixes `#3 <https://github.com/NVIDIA/nsight-python/issues/3>`_ and `#19 <https://github.com/NVIDIA/nsight-python/issues/19>`_).
+
+- **Added support for metric units**: The DataFrame returned by
+  :meth:`~nsight.collection.core.ProfileResults.to_dataframe` now includes a ``Unit`` column. Units for
+  metrics collected with NVIDIA Nsight Compute are parsed directly from the report. For derived
+  metrics, ``derive_metric`` should return a ``(value, unit)`` tuple for a single
+  metric, or a dictionary of ``(value, unit)`` tuples for multiple metrics. Returning
+  only the value remains supported for backward compatibility, but emits a warning and
+  sets ``Unit`` to ``np.nan``.
+
+- **Improved decorated function parameter handling**
+  (`#31 <https://github.com/NVIDIA/nsight-python/pull/31>`_):
+
+  - **Keyword-only parameters** (defined after ``*`` in the signature) are now
+    supported. Config values are mapped correctly to both positional and keyword-only
+    parameters.
+  - **Default parameter values**: configs can now omit trailing parameters that have
+    defaults — missing values are filled in automatically from the function signature.
+  - ``*args`` / ``**kwargs`` no longer cause false validation errors; they are
+    excluded from parameter counting and ignored during profiling.
+
+- **Added cuTile kernel example**
+  (`#37 <https://github.com/NVIDIA/nsight-python/pull/37>`_):
+  Added a new example demonstrating how to profile a CUDA Tile kernel.
+
+API Changes
+-----------
+
+- **Replaced** ``output`` **with** ``verbosity``: The ``output`` parameter of
+  :func:`@nsight.analyze.kernel <nsight.analyze.kernel>`, which accepted the strings
+  ``"quiet"``, ``"progress"``, and ``"verbose"``, has been replaced by a
+  ``verbosity`` parameter of type :class:`~nsight.utils.VerbosityLevel`:
+
+  - ``VerbosityLevel.SILENT`` (replaces ``"quiet"``): suppresses all output.
+  - ``VerbosityLevel.INFO`` (replaces ``"progress"``): shows the progress bar,
+    profiling completion messages, and report file paths. This is the default.
+  - ``VerbosityLevel.DEBUG`` (replaces ``"verbose"``): additionally prints the
+    full NCU CLI command and enables NCU verbose output.
+
+Fixes
+-----
+
+- **Fixed crashes with tuple-valued function arguments**
+  (`#30 <https://github.com/NVIDIA/nsight-python/pull/30>`_):
+  Fixed crashes and corrupted extraction results when profiled functions have
+  tuple-valued arguments. Tuple arguments are now preserved correctly for
+  single- and multi-metric profiling.
+
+- **Fixed crashes with unhashable config parameters**
+  (`#42 <https://github.com/NVIDIA/nsight-python/pull/42>`_):
+  Fixed crashes when aggregating profiling results for configurations containing
+  dictionary- or list-valued arguments. These configuration parameters are now
+  handled consistently regardless of the number of runs.

docs/source/release_notes/topics/updates-in-nsight-python-1.0.0.rst

@@ -5,8 +5,12 @@
 
 from nsight import analyze
 from nsight.annotation import annotate
+from nsight.collection.ncu import try_init_injection
 from nsight.utils import VerbosityLevel, col_panel, row_panel
 
+# Load injection library and symbols for NCU attach (if available)
+try_init_injection()
+
 __version__ = version("nsight-python")
 
 __all__ = ["analyze", "annotate", "VerbosityLevel"]

nsight/__init__.py

@@ -297,14 +297,11 @@ def _create_profiler() -> collection.core.NsightProfiler:
         """Helper to create the profiler with the given settings."""
         # Create the output paths needed for the ncu report, ncu logs and the CSVs
         prefix = output_prefix
-        if "NSPY_NCU_PROFILE" not in os.environ:
-            if prefix is None:
-                prefix = tempfile.mkdtemp(prefix="nspy_")
-                prefix = os.path.join(
-                    prefix, ""
-                )  # Adds a trailing forward/backward slash
-            else:
-                os.makedirs(os.path.dirname(prefix) or ".", exist_ok=True)
+        if prefix is None:
+            prefix = tempfile.mkdtemp(prefix="nspy_")
+            prefix = os.path.join(prefix, "")  # Adds a trailing forward/backward slash
+        else:
+            os.makedirs(os.path.dirname(prefix) or ".", exist_ok=True)
 
         settings = collection.core.ProfileSettings(
             configs=configs,
@@ -476,30 +473,29 @@ def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         def wrapper(*args: Any, **kwargs: Any) -> Any:
             result = func(*args, **kwargs)
 
-            if "NSPY_NCU_PROFILE" not in os.environ:
-                # Legalize the user-provided metric for plotting
-                legalized_metric = _legalize_metric(result, metric)
-
-                visualization.visualize(
-                    result.to_dataframe(),
-                    metric=legalized_metric,
-                    row_panels=row_panels,
-                    col_panels=col_panels,
-                    x_keys=x_keys,
-                    print_data=print_data,
-                    title=title,
-                    filename=filename,
-                    ylabel=ylabel or "",
-                    annotate_points=annotate_points,
-                    show_avg=show_avg,
-                    show_geomean=show_geomean,
-                    plot_type=plot_type,
-                    plot_width=plot_width,
-                    plot_height=plot_height,
-                    variant_fields=variant_fields,
-                    variant_annotations=variant_annotations,
-                    plot_callback=plot_callback,
-                )
+            # Legalize the user-provided metric for plotting
+            legalized_metric = _legalize_metric(result, metric)
+
+            visualization.visualize(
+                result.to_dataframe(),
+                metric=legalized_metric,
+                row_panels=row_panels,
+                col_panels=col_panels,
+                x_keys=x_keys,
+                print_data=print_data,
+                title=title,
+                filename=filename,
+                ylabel=ylabel or "",
+                annotate_points=annotate_points,
+                show_avg=show_avg,
+                show_geomean=show_geomean,
+                plot_type=plot_type,
+                plot_width=plot_width,
+                plot_height=plot_height,
+                variant_fields=variant_fields,
+                variant_annotations=variant_annotations,
+                plot_callback=plot_callback,
+            )
             return result
 
         return wrapper