jupyterlab-nvidia-nsight 0.7.0

A JupyterLab extension for profiling cells execution using NVIDIA Nsight tools.

NVIDIA Nsight Tools JupyterLab Extension

A JupyterLab extension for profiling cells execution using NVIDIA Nsight tools.

Demo

Click on the image to launch the video

Requirements

• JupyterLab >= 4.0.0
• Docker (optional, for GUI support)
• nvtx (Required for Nsight Compute support)

Nsight tools are not shipped with this extension. The required tool(s) should be installed separately on the JupyterLab server machine.

Install and setup

• To install the extension, execute:

pip install jupyterlab-nvidia-nsight

• Install Nsight Systems and/or Nsight Compute (these tools are not shipped with this extension).

• Set Nsight Systems and/or Nsight Compute installation location in the extension settings.

  • Example: If Nsight Systems installation location is set to /opt/nvidia/nsight-systems/<version>, then the extension will look for nsys executable in /opt/nvidia/nsight-systems/<version>/target-linux-x64
  • If not set, PATH environment variable should contain the locations of the tool's executables.

Profile JupyterLab cells

1. Enable Nsight tool by using the Profiling with Nsight Systems/Compute... command under the NVIDIA Nsight menu, or by using the command palette.
   • Note: This operation restarts the JupyterLab kernel.
2. Profile cells execution by using the Run and profile selected cells... command.
3. The cell's profiling info is displayed in the cell output area.

Analyzing the profile session in Nsight tools GUI

• Open Nsight tools report files in a tab inside JupyterLab.

• Display of Nsight tools GUI requires NVIDIA Nsight Streamer.

• When JupyterLab is running inside a Docker container, displaying Nsight tools UI requires to have the Docker daemon socket mounted (i.e., docker run -v /var/run/docker.sock:/var/run/docker.sock ...).

  • SECURITY ALERT: The Docker daemon socket should not be mounted when using untrusted sources, as it may provide root access to the host system.
  • See also Docker Example.

Supported Tools

Nsight Systems

• Supports Nsight Systems release 2024.1.1 or later. It is recommended to use the latest release.
• Use --stats=true when profiling cells execution to see textual output of nsys stats.

List of NSYS CLI flags that can't be used within the extension:

• --help, -h
• --hotkey-capture
• --output, -o
• --session-new
• --session
• --stop-on-exit, -x

Nsight Compute

• Supports Nsight Compute release 2024.3 or later. It is recommended to use the latest release.

List of NCU CLI flags that can't be used within the extension:

• --app-replay-buffer
• --app-replay-match
• --app-replay-mode
• --check-exit-code
• --chips
• --config-file-path
• --config-file
• --export, -o
• --force-overwrite, -f
• --help, -h
• --hostname
• --import, -i
• --kill
• --list-chips
• --list-metrics
• --list-rules
• --list-sections
• --list-sets
• --log-file
• --mode
• --null-stdin
• --open-in-ui
• --profile-from-start
• --query-metrics-collection
• --query-metrics-mode
• --query-metrics
• --quiet
• --range-filter
• --range-replay-options
• --rename-kernels-export
• --replay-mode
• --section-folder-restore
• --version, -v

List of NCU CLI flags that can be used only when enabling NCU:

• --apply-rules
• --cache-control
• --call-stack-type
• --call-stack
• --clock-control
• --disable-profiler-start-stop
• --graph-profiling
• --import-source
• --injection-path-32
• --injection-path-64
• --max-connections
• --metrics
• --pm-sampling-buffer-size
• --pm-sampling-interval
• --pm-sampling-max-passes
• --port, -p
• --preload-library
• --rule
• --section-folder-recursive
• --section-folder
• --section
• --set
• --source-folders
• --support-32bit
• --target-processes-filter
• --target-processes
• --verbose
• --warp-sampling-buffer-size
• --warp-sampling-interval
• --warp-sampling-max-passes

List of NCU CLI flags that can be used only when profiling cells:

• --csv
• --devices
• --disable-extra-suffixes
• --filter-mode
• --kernel-id
• --kernel-name-base
• --kernel-name, -k
• --launch-count, -c
• --launch-skip-before-match
• --launch-skip, -s
• --nvtx-exclude
• --nvtx-include
• --page
• --print-details
• --print-fp
• --print-kernel-base
• --print-metric-attribution
• --print-metric-instances
• --print-metric-name
• --print-nvtx-rename
• --print-rule-details
• --print-source
• --print-summary
• --print-units
• --rename-kernels-path
• --rename-kernels
• --resolve-source-file

Docker Example

This example demonstrates how to use the extension in a Jupyter Docker Stacks image.

The following Dockerfile defines a Docker image based on pytorch-notebook with cuda12, and includes the extension and cuda-toolkit.
It is recommended to use the latest cuda-toolkit - https://developer.nvidia.com/cuda-downloads

FROM quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8

# Install cuda-tookit
ADD https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb /tmp/
USER root
RUN dpkg -i /tmp/cuda-keyring_1.1-1_all.deb && apt-get -y update && \
    apt-get -y install cuda-toolkit-12-8
USER ${NB_UID}

# Install jupyterlab-nvidia-nsight and set the default settings
ARG HOST_IP
RUN pip install --no-cache-dir jupyterlab-nvidia-nsight nvtx && \
    fix-permissions "${CONDA_DIR}" && fix-permissions "/home/${NB_USER}" && \
    mkdir -p /home/${NB_USER}/.jupyter/lab/user-settings/jupyterlab-nvidia-nsight && echo ' \
{ \
    "ui": { \
        "enabled": true, \
        "suppressServerAddressWarning": true, \
        "dockerHost": "'"$HOST_IP"'" \
    }, \
    "nsys": { \
        "installationPath": "/opt/nvidia/nsight-systems/2024.6.2", \
        "args": "--trace=cuda,nvtx,osrt --python-sampling=true --python-backtrace=cuda --cudabacktrace=all" \
    }, \
    "ncu": { \
        "installationPath": "/opt/nvidia/nsight-compute/2025.1.1" \
    } \
}' > /home/${NB_USER}/.jupyter/lab/user-settings/jupyterlab-nvidia-nsight/plugin.jupyterlab-settings

Build the image:

docker build --rm --tag <your-image-name> --build-arg HOST_IP="$(hostname -i | cut -d' ' -f1)" .

Run the container:

# SECURITY ALERT: Remove `-v /var/run/docker.sock:/var/run/docker.sock` when using untrusted sources
docker run -it --rm --group-add $(getent group docker | cut -d: -f3) --runtime=nvidia -p 8888:8888 -v /var/run/docker.sock:/var/run/docker.sock <your-image-name>

Note: Using --runtime=nvidia requires NVIDIA Container Toolkit.

Uninstall

To remove the extension, execute:

pip uninstall jupyterlab-nvidia-nsight

Troubleshooting

If you are seeing the frontend extension, but it is not working, check that the server extension is enabled:

jupyter server extension list

If the server extension is installed and enabled, but you are not seeing the frontend extension, check the frontend extension is installed:

jupyter labextension list

Known Issues

• While Nsight Compute is enabled, interrupting the JupyterLab kernel with the "Interrupt Kernel" command (by using the command palette, kernel menu or the stop-button) causes the kernel to terminate and restart.

Release Notes

0.7.0

• New setting for configuring the location of the generated reports.
• Support displaying Nsight UI when running inside a docker container.
• Use (and pull if required) the latest NVIDIA Nsight Streamer for displaying Nsight UI.
  • See Nsight Streamer for Nsight Systems and Nsight Streamer for Nsight Compute.
• Support displaying an external WebRTC streamer.

0.6.0

• Support displaying Nsight Compute UI inside JupyterLab.
• Fix keyboard interaction with Nsight tools UI.

0.5.2

• Added Nsight Compute section in the project description.
• Verify server connection on extension load.

0.5.1

• Initial release.