NVIDIA Nsight Systems

https://docs.nvidia.com/nsight-systems/
Admin
NVIDIA Nsight Systems is a performance profiling and analysis tool for optimizing GPU and CPU...
Tokens:205,838
Snippets:1,452
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Ubuntu minimal container setup: install nsight-systems-cli

Source: https://docs.nvidia.com/nsight-systems/InstallationGuide/index.html

Commands for installing the CLI-only package in a minimal Ubuntu container. Assumes root access; example container launch: sudo docker run -it --rm ubuntu:latest bash.

```bash
apt update
apt install -y --no-install-recommends gnupg
echo "deb http://developer.download.nvidia.com/devtools/repos/ubuntu$(source /etc/lsb-release; echo "$DISTRIB_RELEASE" | tr -d .)/$(dpkg --print-architecture) /" | tee /etc/apt/sources.list.d/nvidia-devtools.list
apt-key adv --fetch-keys http://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/7fa2af80.pub
apt update
apt install nsight-systems-cli
```

--------------------------------

### Install all Nsight Systems recipe dependencies

Source: https://docs.nvidia.com/nsight-systems/InstallationGuide/index.html

One-step installation of all dependencies for CLI and GUI. Activate the venv first to ensure modules are installed into the venv.

```bash
$ python3 -m pip install -r nsys_recipe/requirements/dask.txt -r nsys_recipe/requirements/common.txt -r nsys_recipe/requirements/jupyter.txt
```

--------------------------------

### ImportNvtxt info example

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Example of using the info command on a report file, showing the output with start and end times.

```text
ImportNvtxt info Report.nsys-rep
Analysis start (ns) 83501026500000
Analysis end (ns)   83506375000000
```

--------------------------------

### CentOS and RHEL minimal container setup: install nsight-systems-cli

Source: https://docs.nvidia.com/nsight-systems/InstallationGuide/index.html

Commands for installing the CLI-only package in a minimal CentOS/RHEL container. Assumes root access; example container launch: sudo docker run -it --rm centos:latest bash.

```bash
rpm --import https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/7fa2af80.pub
sed -i 's/mirrorlist/#mirrorlist/g' /etc/yum.repos.d/CentOS-*
sed -i 's|#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|g' /etc/yum.repos.d/CentOS-*
dnf install -y 'dnf-command(config-manager)'
dnf config-manager --add-repo "https://developer.download.nvidia.com/devtools/repos/rhel$(source /etc/os-release; echo ${VERSION_ID%%.*})/$(rpm --eval '%{_arch}' | sed s/aarch/arm/)/"
dnf install -y nsight-systems-cli
```

--------------------------------

### Ubuntu desktop: install nsight-systems

Source: https://docs.nvidia.com/nsight-systems/InstallationGuide/index.html

Commands for installing the full Nsight Systems package on an Ubuntu desktop using apt.

```bash
sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/7fa2af80.pub
sudo add-apt-repository "deb https://developer.download.nvidia.com/devtools/repos/ubuntu$(source /etc/lsb-release; echo "$DISTRIB_RELEASE" | tr -d .)/$(dpkg --print-architecture)/ /"
sudo apt install nsight-systems
```

--------------------------------

### Download and install Nsight Systems dependencies offline

Source: https://docs.nvidia.com/nsight-systems/InstallationGuide/index.html

Two-step installation for machines without internet. Download wheel packages on an internet-connected machine, transfer the tarball, then install locally with --no-index.

```bash
$  python3 -m pip download -r nsys_recipe/requirements/dask.txt -r nsys_recipe/requirements/common.txt -r nsys_recipe/requirements/jupyter.txt -d “recipe-deps”
```

```bash
$ tar -cvfz recipe-deps.tar.gz recipe-deps
```

```bash
$ tar -xvfz recipe-deps.tar.gz
```

```bash
$ python3 -m pip install recipe-deps/* --no-index
```

--------------------------------

### Run Dependency Installer Without Root and Launch GUI

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Installs dependencies without root into a user-writable directory, then sets up the environment and launches the GUI.

```bash
[installation_path]/host-linux-[arch]/Scripts/DependenciesInstaller/install-dependencies-without-root.sh [dependencies_path]
```

```bash
source [installation_path]/host-linux-[arch]/Scripts/DependenciesInstaller/setup-dependencies-environment.sh [dependencies_path] && [installation_path]/host-linux-[arch]/nsys-ui
```

--------------------------------

### Run flashing Docker container (generic and version-specific examples)

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Runs the flashing Docker container, mounting the USB device and a temporary directory. Replace `<docker image>` with the actual image link; concrete examples are provided for DRIVE OS 6.0.8.0 and 6.0.9.1 QNX, and 6.0.8.0 Linux.

```bash
sudo docker run --rm --privileged --net host \
    -v /dev/bus/usb:/dev/bus/usb \
    -v /tmp:/drive_flashing \
    -it <docker image>

```

```bash
sudo docker run --rm --privileged --net host \
    -v /dev/bus/usb:/dev/bus/usb \
    -v /tmp:/drive_flashing \
    -it nvcr.io/{MY_NGC_ORG}/driveos-pdk/drive-agx-orin-qnx-aarch64-pdk-build-x86:6.0.8.0-0003

```

```bash
sudo docker run --rm --privileged --net host \
    -v /dev/bus/usb:/dev/bus/usb \
    -v /tmp:/drive_flashing \
    -it nvcr.io/{MY_NGC_ORG}/driveos-pdk/drive-agx-orin-qnx-aarch64-pdk-build-x86:6.0.9.1-latest

```

```bash
sudo docker run --rm --privileged --net host \
    -v /dev/bus/usb:/dev/bus/usb \
    -v /tmp:/drive_flashing \
    -it nvcr.io/{MY_NGC_ORG}/driveos-pdk/drive-agx-orin-linux-aarch64-pdk-build-x86:6.0.8.0-0003

```

--------------------------------

### Create recipe directory and copy template files

Source: https://docs.nvidia.com/nsight-systems/AnalysisGuide/index.html

Create the recipe directory and copy the existing recipe files into it. Run these commands in the recipe package folder to set up the new recipe with the required metadata, notebook, and script files.

```bash
> cd <install-dir>/target-linux-x64/python/packages/nsys_recipe
> mkdir new_metric_util_map
> cp gpu_metric_util_map/metadata.json new_metric_util_map/metadata.json
> cp gpu_metric_util_map/heatmap.ipynb new_metric_util_map/heatmap.ipynb
> cp gpu_metric_util_map/gpu_metric_util_map.py new_metric_util_map/new_metric_util_map.py

```

--------------------------------

### NVTX capture range: message@* example

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Profiling starts when the first NVTX range with message 'profiler' in any domain is opened.

```shell
nsys launch -w true -p 'profiler@*' ./app

```

--------------------------------

### Enroot pre-start hook to bind-mount Nsights Systems and set PATH

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Use this hook only when you need conditional behavior, e.g., pick a different Nsights Systems install based on the image or the host's GPU family. Hooks live in `/etc/enroot/hooks.d/` with a `.sh` extension, run with full capabilities before the container switches to its final root, and receive `ENROOT_ROOTFS`, `ENROOT_MOUNTS`, and `ENROOT_ENVIRON`.

```bash
#!/usr/bin/env bash
# Append a bind mount for Nsights Systems to the container's mount file,
# and add it to PATH via the environ file. Prefer mounts.d / environ.d
# unless you actually need logic here.

set -euo pipefail

: "${ENROOT_MOUNTS:?not set}"
: "${ENROOT_ENVIRON:?not set}"

NSYS_HOST_PREFIX="/opt/nvidia/nsight-systems/2026.2.1"
NSYS_IN_CONTAINER="/opt/nvidia/nsight-systems/2026.2.1"

echo "${NSYS_HOST_PREFIX} ${NSYS_IN_CONTAINER} none bind,ro,nosuid,nodev 0 0" \
    >> "${ENROOT_MOUNTS}"
echo "PATH=${NSYS_IN_CONTAINER}/bin:\${PATH}" >> "${ENROOT_ENVIRON}"
```

--------------------------------

### NVTX capture range: message example

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Profiling starts when the first NVTX range with message 'profiler' in the default domain is opened.

```shell
nsys launch -w true -p profiler ./app

```

--------------------------------

### NVTX capture range: message@domain example

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Profiling starts when the first NVTX range with message 'profiler' in domain 'service' is opened.

```shell
nsys launch -w true -p profiler@service ./app

```

--------------------------------

### vClock plugin setup and profiling commands

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

The vClock plugin setup and initialization commands for cross-system report alignment. The first command starts a provider on each host, listing peer IPs; the second enables the plugin during profiling. Providers must be left running until all profiling sessions are complete.

```shell
<nsys-target-dir>/plugins/vclock/vclock_plugin --peers <peer-ip>[,<peer-ip>,...]
```

```shell
nsys profile --enable "vclock" <application>
```

--------------------------------

### CLI Export Command Output in test.sqlite

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Example showing how the output name starting with '@' is interpreted as a command and the report output is piped to its stdin. The text is a comment or description of the functionality and is part of the displayed code block.

```text
Effect: Open test.sqlite and run the `cuda_api_sum` script on that file. Generate table data and feed that into the command `grep -E (-|Name|cudaFree)`. The grep command will filter out everything but the header, formatting, and the `cudaFree` data, and display the results to the console.

```

--------------------------------

### Launch binary with LD_PRELOAD launcher library

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Launches a binary with the preload launcher library so the process sends itself SIGSTOP, stopping it before any application code runs. The process becomes a background job; use jobs -l to see its PID, and Nsight Systems sends SIGCONT when attaching.

```bash
$ LD_PRELOAD=/opt/nvidia/nsight_systems/libLauncher64.so ./my-aarch64-binary --arguments
```

--------------------------------

### Install pip and venv on Ubuntu

Source: https://docs.nvidia.com/nsight-systems/InstallationGuide/index.html

Install pip and venv on Ubuntu for the Nsight Systems multi-report analysis system. Run both commands if pip and venv are not already installed. On a fresh Ubuntu install, run sudo apt-get update first.

```bash
sudo apt-get install python3-pip
```

```bash
sudo apt-get install python3-venv
```

--------------------------------

### List Available GPUs with --gpu-metrics-devices=help

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Lists available GPU devices and their supported statuses, including options 'all', 'cuda-visible', 'none', and notes about unsupported GPUs.

```bash
$ nsys profile --gpu-metrics-devices=help
Possible --gpu-metrics-devices values are:
    1: Turing TU104 | GeForce RTX 2070 SUPER PCI[0000:65:00.0]
    all: Select all supported GPUs
    cuda-visible: Select GPUs that match CUDA_VISIBLE_DEVICES
    none: Disable GPU Metrics [Default]
Some GPUs are not supported:
    0: Volta GV100 | Quadro GV100 PCI[0000:17:00.0]
See the user guide: https://docs.nvidia.com/nsight-systems/UserGuide/index.html#gpu-metrics

```

--------------------------------

### Update apt packages on fresh Ubuntu

Source: https://docs.nvidia.com/nsight-systems/InstallationGuide/index.html

Run on a fresh Ubuntu install before installing pip and venv. This updates the package index and is a prerequisite for the apt-get install commands.

```bash
sudo apt-get update
```

--------------------------------

### ImportNvtxt create example

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Example of creating a report from a NVTXT file. The output is a new report file that can be opened in Nsight Systems.

```text
ImportNvtxt --cmd create -n Sample.nvtxt -o Report.nsys-rep
```

--------------------------------

### Delayed start run: nsys profile -e TEST_ONLY=0 -y 20

Source: https://docs.nvidia.com/nsight-systems/UserGuide/index.html

Delayed start run: sets environment variable TEST_ONLY=0 and delays profiling start by 20 seconds.

```bash
nsys profile -e TEST_ONLY=0 -y 20
    <application> [application-arguments]
```
Tokens:
Raw