Installation and Setup#

Installation and Setup Essentials for NVIDIA Nsight Visual Studio Code Edition

Installation and Setup Essentials#

To reduce the chance of encountering problems when installing the NVIDIA Nsight Visual Studio Code Edition tools, consider several items in advance. For example, determine whether you want to run the tools on one machine and debug your application on another, or if you will debug on a single machine. Performing remote debugging can be advantageous because the Visual Studio environment will continue to run on the host machine even if the target machine has to be rebooted because an application crash.

Remote debugging allows you to debug over a network, which means that a target machine can be made easily available to a development team, or to members who do not have physical access to the target GPU.

Before You Start

Task

For more information, see…

Install the prerequisite software.

You must have the prerequisite software on your host and target machines, using the versions recommended in the release notes for a qualified experience:

IDE Host : Microsoft Visual Studio Code.
Toolkit : NVIDIA CUDA Toolkit. See the CUDA Toolkit’s Quick Start Guide for installation instructions.
Driver : NVIDIA display driver. Ideally, use the the driver in the CUDA Toolkit.

Review the hardware and software requirements for the product to make sure that you have the minimum or recommended configurations.

System Requirements for NVIDIA® Nsight™ Visual Studio Code software.

Review the overview of installation procedures to make sure you understand the ways that you can configure your development system.

Target and Host Setup.

System Requirements for NVIDIA Nsight VSCE Software#

A debugging setup with Nsight VSCE has three layers, which may live on one machine or be split across machines:

IDE host: the machine running Visual Studio Code (or a compatible editor such as VSCodium). Windows and macOS can serve as the IDE host when paired with Remote-SSH or WSL as described in Target and Host Setup.
Extension and debug host: the machine where the Nsight VSCE extension and cuda-gdb run. Linux x86_64 and Linux arm64 are supported.
Debuggee target: the machine where the CUDA application runs. This is the debug host itself for local debugging, or a remote Linux (x86_64 or arm64) or QNX (arm64) system reached via cuda-gdbserver for remote debugging.

	Minimum	Recommended
IDE Host	Microsoft Visual Studio Code 1.101 or later, or a compatible editor such as VSCodium (installing from the Open VSX Registry).	Please see the release notes for the recommended Microsoft Visual Studio Code version.
Host Operating System (extension/debug host)	Linux x86_64 and Linux arm64. Nsight VSCE is based on cuda-gdb, which supports the Linux operating systems supported by the CUDA Toolkit.	Minimum or higher
Target Operating System	Linux x86_64 and Linux arm64 as local or remote debugging targets, and QNX arm64 as a remote target. For information on remote debugging (where the host is different than the target), please visit cuda-gdb’s remote debugging documentation.	Minimum or higher
CPU	Intel(R) Pentium(R) Dual-core CPU or equivalent @ 1.6 GHz minimum	Intel(R) Pentium(R) Dual-core CPU or equivalent @ 2.2 GHz or higher
Memory	2 GB minimum	2 GB or more
Hard Disk Space	330 MB for NVIDIA Nsight™ VSCE software	On a 64-bit machine with NVIDIA Nsight™ VSCE Host software: 330 MB plus space for your project files. If using remote machine to run/debug target application, remote machine: 240 MB plus space for the debug version of your target application.
Target Machine GPU Hardware	CUDA GPUs lists CUDA-enabled devices and their compute capabilities. CUDA Compute Capabilities gives the technical specifications of each compute capability.	Latest supported NVIDIA GPU
CUDA Toolkit	You must install an NVIDIA CUDA Toolkit that supports NVIDIA Nsight™ VSCE.	Please see the release notes for the recommended CUDA Toolkit version.
Display Driver	You must install an NVIDIA display driver that supports NVIDIA Nsight™ VSCE. Typically, this comes with the NVIDIA CUDA Toolkit and can be installed as a CUDA Toolkit option.	Please see the release notes for the recommended NVIDIA display driver version.

Note

Windows users can also debug CUDA applications running inside WSL 2 (Windows Subsystem for Linux 2) directly from VS Code on the Windows host. This requires additional setup including a registry key and optional TDR configuration. See Local Debugging in WSL 2 on Windows for details.

Compute Debugger Supported Configurations#

NVIDIA Nsight Visual Studio Code Edition support for NVIDIA GPUs is dependent on the associated CUDA Toolkit support for those GPUs. Please refer to the CUDA Toolkit documentation for supported GPU SMs.

How To: Install NVIDIA Nsight Visual Studio Code Edition#

The NVIDIA Nsight Visual Studio Code Edition is an extension to Microsoft Visual Studio Code which supports GPU computing by providing

Declarative language configuration for CUDA syntax highlighting, bracket matching, code folding, auto-indention, etc.
C++ language server extensions to support CUDA-specific language features.
Debugger views to provide CUDA-specific debugging information.
IDE extensions to add productivity enhancements to the VS Code environment.

To begin, you simply need to download and install the Nsight VSCE extension.

Install the NVIDIA Nsight VSCE Software#

The Nsight VSCE extension can be installed directly from within Visual Studio Code via the Extensions tab.

Search for Nsight in the Extensions tab.
Press Install to add the extension to Visual Studio Code.

The extension is published both on the Visual Studio Marketplace (used by Microsoft Visual Studio Code) and on the Open VSX Registry (used by VSCodium and other compatible editors), so the Extensions-tab installation works the same way in either editor.

Alternatively, you can download the extension from the Visual Studio Marketplace or the Open VSX Registry.

Search for Nsight.
Click the download button to download a VSIX file.
In the Extensions tab execute the Install from VSIX... command. This command can also be run from the Microsoft Visual Studio Code Command Palette.
Browse to the downloaded VSIX file, select it, and click Install.

Target and Host Setup#

NVIDIA Nsight™ VSCE allows you to debug your applications in two different ways:

Local debugging, in which the host and target are on the same machine.
Remote debugging, in which the host and target are on two different machines.

Local Debugging#

If you configure your system for local debugging, you will use a single computer to build the project and run the application to be debugged. This means that you will need to have one or more GPUs in your computer, and must meet minimum requirements. Note that CUDA debugging only requires one GPU.

Supported target machine (including local debugging) platforms are Linux x86 and Linux arm (SBSA).

See System Requirements for a list of supported GPUs and platforms.

Local Debugging in WSL 2 on Windows#

WSL 2 (Windows Subsystem for Linux 2) allows you to run a Linux-based CUDA debugging session on a Windows host using Nsight Visual Studio Code Edition. The debugger connects to cuda-gdb running inside WSL 2, enabling GPU debugging without a separate Linux machine.

Supported Platforms#

OS: Windows 10 or Windows 11
Driver: Install the NVIDIA Windows GPU driver only. Do not install a Linux GPU driver inside WSL 2.
CUDA Toolkit: Use the WSL-Ubuntu variant from the CUDA Toolkit Downloads page. Do not use the standard Linux installer as it may overwrite the Windows driver stub (libcuda.so) inside WSL 2.

Prerequisites#

Before starting a debug session, complete the following steps on the Windows host.

1. Enable the GPU Debug Interface

The GPU debug interface must be enabled via a Windows registry key.

Open Registry Editor (regedit) on Windows.

Navigate to:

HKEY_LOCAL_MACHINE\SOFTWARE\NVIDIA Corporation\GPUDebugger

Verify that the EnableInterface value exists and is set to DWORD 1. If it does not exist, create a new DWORD (32-bit) value named EnableInterface and set it to 1.

Note

Without this registry key, cuda-gdb will display the following warning and GPU debugging will not function:

WARNING: Debug interface is not enabled. Please see
https://docs.nvidia.com/cuda/cuda-gdb/index.html#supported-platforms
for more details.

The application will run to completion without hitting any breakpoints.

2. Configure TDR (Timeout Detection and Recovery)

Windows terminates GPU operations that exceed the default TDR timeout of 2 seconds. This can interrupt long debug sessions. For debugging compute-intensive applications, increase or disable the TDR timeout.

See TDR Registry Keys for instructions on modifying the TDR settings.

Note

A system reboot is required after modifying TDR registry settings.

3. Python Version Compatibility

Use a WSL Ubuntu release whose default python3 version is supported by the cuda-gdb version installed with your CUDA Toolkit. cuda-gdb selects a Python-enabled debugger binary based on the Python version available on the system.

See cuda-gdb Supported Platforms for the list of supported Python versions.

Note

If cuda-gdb reports that Python was not initialized, verify that your WSL distribution has a supported python3 and a matching libpython installed from the distro packages. See cuda-gdb Common Issues on Supported Operating Systems for further guidance.

4. Open the Project in VS Code (WSL Remote)

Open your CUDA project from a VS Code window connected to the target WSL distro using the Remote - WSL extension. Ensure the following are installed in the WSL remote extension host:

Nsight Visual Studio Code Edition — install it in the WSL context, not just on the Windows host.
CUDA Toolkit (WSL-Ubuntu variant) — must be installed inside WSL, including cuda-gdb.

Note

Extensions installed on the Windows side of VS Code are not automatically available in the WSL remote host. Use Extensions > Install in WSL to ensure Nsight is active in the correct context.

Setting Up a Debug Session#

1. Compile with Debug Symbols

Inside WSL 2, compile your CUDA application with debug symbols:

nvcc -g -G your_application.cu -o your_application

2. Configure launch.json

In VS Code, create or update .vscode/launch.json with the following configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "CUDA C++: Launch",
            "type": "cuda-gdb",
            "request": "launch",
            "program": "${workspaceFolder}/your_application"
        }
    ]
}

3. Start Debugging

Open the project folder in VS Code connected to WSL 2.
Set a breakpoint inside a CUDA kernel by clicking the left margin next to the line number.
Press F5 or select Run > Start Debugging.
Select CUDA C++: Launch from the configuration dropdown.

When the kernel executes, the debugger will pause at the breakpoint. Kernel variables, registers, and the call stack are visible in the VS Code debug panels.

Known Limitations#

Attach is not supported on WSL 2. Attempting to attach to a running CUDA process will fail. This is a WSL 2 driver-level restriction — the Windows GPU driver does not permit late attachment from within the WSL 2 environment. The following error messages will be observed:
- cuda-gdb 13.3: Failed to open file to trigger safe library injection

Additional Resources#

Remote Debugging#

If you choose to configure your systems for remote debugging, you will use one computer as the host machine. The host machine will run Visual Studio Code to build your project, as well as to launch debugging sessions.

Meanwhile, a separate computer is configured as the target machine. The target will run the application to be debugged.

To perform remote debugging first install the Remote-SSH Visual Studio Code extension. Use Remote-SSH to connect to the target machine to edit, build, and debug your project, similarly to if the project were local. For more information on developing projects remotely via Remote-SSH, see Remote Development using SSH and the Remote Development over SSH tutorial.

Performing remote debugging this way can be advantageous because the Visual Studio environment will continue to run on the host machine, even if the target machine has to be rebooted because of an application crash. Remote debugging also allows you to debug over a network, which means that a target machine can be made easily available to a development team, or to members who do not have physical access to the target GPU.

Install the NVIDIA Display Driver#

It is recommended that you download and install the NVIDIA display driver for the installed CUDA Toolkit. See the release notes for more information.

If you have an NVIDIA graphics card installed on your target machine, you probably already have an NVIDIA display driver. However, NVIDIA Nsight Visual Studio Code Edition requires an updated version of the driver in order to function properly. Please see the latest release notes for compatible driver versions.

Also review the System Requirements (Target Machine GPU Hardware) to ensure that your GPU is supported.

Working with Samples#

CUDA Samples can be downloaded for use with NVIDIA Nsight Visual Studio Code Edition tools via the NVIDIA CUDA Toolkit or the NVIDIA/cuda-samples repository on GitHub.

Notices

Notice

^{NVIDIA® Nsight™ Application Development Environment for Heterogeneous Platforms, Visual Studio Code Edition 2026.1.0 User Guide}

Send Feedback

^{THE INFORMATION IN THIS GUIDE AND ALL OTHER INFORMATION CONTAINED IN NVIDIA DOCUMENTATION REFERENCED IN THIS GUIDE IS PROVIDED “AS IS.” NVIDIA MAKES NO WARRANTIES, EXPRESSED, IMPLIED, STATUTORY, OR OTHERWISE WITH RESPECT TO THE INFORMATION FOR THE PRODUCT, AND EXPRESSLY DISCLAIMS ALL IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE. Notwithstanding any damages that customer might incur for any reason whatsoever, NVIDIA’s aggregate and cumulative liability towards customer for the product described in this guide shall be limited in accordance with the NVIDIA terms and conditions of sale for the product.}

^{THE NVIDIA PRODUCT DESCRIBED IN THIS GUIDE IS NOT FAULT TOLERANT AND IS NOT DESIGNED, MANUFACTURED OR INTENDED FOR USE IN CONNECTION WITH THE DESIGN, CONSTRUCTION, MAINTENANCE, AND/OR OPERATION OF ANY SYSTEM WHERE THE USE OR A FAILURE OF SUCH SYSTEM COULD RESULT IN A SITUATION THAT THREATENS THE SAFETY OF HUMAN LIFE OR SEVERE PHYSICAL HARM OR PROPERTY DAMAGE (INCLUDING, FOR EXAMPLE, USE IN CONNECTION WITH ANY NUCLEAR, AVIONICS, LIFE SUPPORT OR OTHER LIFE CRITICAL APPLICATION). NVIDIA EXPRESSLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR SUCH HIGH RISK USES. NVIDIA SHALL NOT BE LIABLE TO CUSTOMER OR ANY THIRD PARTY, IN WHOLE OR IN PART, FOR ANY CLAIMS OR DAMAGES ARISING FROM SUCH HIGH RISK USES.}

^{NVIDIA makes no representation or warranty that the product described in this guide will be suitable for any specified use without further testing or modification. Testing of all parameters of each product is not necessarily performed by NVIDIA. It is customer’s sole responsibility to ensure the product is suitable and fit for the application planned by customer and to do the necessary testing for the application in order to avoid a default of the application or the product. Weaknesses in customer’s product designs may affect the quality and reliability of the NVIDIA product and may result in additional or different conditions and/or requirements beyond those contained in this guide. NVIDIA does not accept any liability related to any default, damage, costs or problem which may be based on or attributable to: (i) the use of the NVIDIA product in any manner that is contrary to this guide, or (ii) customer product designs.}

^{Other than the right for customer to use the information in this guide with the product, no other license, either expressed or implied, is hereby granted by NVIDIA under this guide. Reproduction of information in this guide is permissible only if reproduction is approved by NVIDIA in writing, is reproduced without alteration, and is accompanied by all associated conditions, limitations, and notices.}

Trademarks

^{NVIDIA, the NVIDIA logo, and cuBLAS, CUDA, CUDA-GDB, CUDA-MEMCHECK, cuDNN, cuFFT, cuSPARSE, DIGITS, DGX, DGX-1, DGX Station, NVIDIA DRIVE, NVIDIA DRIVE AGX, NVIDIA DRIVE Software, NVIDIA DRIVE OS, NVIDIA Developer Zone (aka “DevZone”), GRID, Jetson, NVIDIA Jetson Nano, NVIDIA Jetson AGX Xavier, NVIDIA Jetson TX2, NVIDIA Jetson TX2i, NVIDIA Jetson TX1, NVIDIA Jetson TK1, Kepler, NGX, NVIDIA GPU Cloud, Maxwell, Multimedia API, NCCL, NVIDIA Nsight Compute, NVIDIA Nsight Eclipse Edition, NVIDIA Nsight Graphics, NVIDIA Nsight Integration, NVIDIA Nsight Systems, NVIDIA Nsight Visual Studio Edition, NVIDIA Nsight Visual Studio Code Edition, NVLink, nvprof, Pascal, NVIDIA SDK Manager, Tegra, TensorRT, Tesla, Visual Profiler, VisionWorks and Volta are trademarks and/or registered trademarks of NVIDIA Corporation in the United States and other countries. Other company and product names may be trademarks of the respective companies with which they are associated.}