One of the key features of Visual Studio Code is its great debugging support. VS Code's built-in debugger helps accelerate your edit, compile, and debug loop.
Debugger extensions
VS Code has built-in debugging support for the Node.js runtime and can debug JavaScript, TypeScript, or any other language that gets transpiled to JavaScript.
For debugging other languages and runtimes [including PHP, Ruby, Go, C#, Python, C++, PowerShell and many others], look for Debuggers extensions in the VS Code Marketplace or select Install Additional Debuggers in the top-level Run menu.
Below are several popular extensions which include debugging support:
Tip: The extensions shown above are dynamically queried. Select an extension tile above to read the description and reviews to decide which extension is best for you.
Start debugging
The following documentation is based on the built-in Node.js debugger, but most of the concepts and features are applicable to other debuggers as well.
It is helpful to first create a sample Node.js application before reading about debugging. You can follow the Node.js walkthrough to install Node.js and create a simple "Hello World" JavaScript application [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
0]. Once you have a simple application set up, this page will take you through VS Code debugging features.
Run and Debug view
To bring up the Run and Debug view, select the Run and Debug icon in the Activity Bar on the side of VS Code. You can also use the keyboard shortcut ⇧⌘D [Windows, Linux Ctrl+Shift+D].
The Run and Debug view displays all information related to running and debugging and has a top bar with debugging commands and configuration settings.
If running and debugging is not yet configured [no
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
1 has been created], VS Code shows the Run start view.
The top-level Run menu has the most common run and debug commands:
Launch configurations
To run or debug a simple app in VS Code, select Run and Debug on the Debug start view or press F5 and VS Code will try to run your currently active file.
However, for most debugging scenarios, creating a launch configuration file is beneficial because it allows you to configure and save debugging setup details. VS Code keeps debugging configuration information in a
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
1 file located in a
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
3 folder in your workspace [project root folder] or in your or .
To create a
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
1 file, click the create a launch.json file link in the Run start view.
VS Code will try to automatically detect your debug environment, but if this fails, you will have to choose it manually:
Here is the launch configuration generated for Node.js debugging:
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"skipFiles": ["/**"],
"program": "${workspaceFolder}\\app.js"
}
]
}
If you go back to the File Explorer view [⇧⌘E [Windows, Linux Ctrl+Shift+E]], you'll see that VS Code has created a
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
3 folder and added the
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
1 file to your workspace.
Note: You can debug a simple application even if you don't have a folder open in VS Code, but it is not possible to manage launch configurations and set up advanced debugging. The VS Code Status Bar is purple if you do not have a folder open.
Note that the attributes available in launch configurations vary from debugger to debugger. You can use IntelliSense suggestions [⌃Space [Windows, Linux Ctrl+Space]] to find out which attributes exist for a specific debugger. Hover help is also available for all attributes.
Do not assume that an attribute that is available for one debugger automatically works for other debuggers too. If you see green squiggles in your launch configuration, hover over them to learn what the problem is and try to fix them before launching a debug session.
Review all automatically generated values and make sure that they make sense for your project and debugging environment.
Launch versus attach configurations
In VS Code, there are two core debugging modes, Launch and Attach, which handle two different workflows and segments of developers. Depending on your workflow, it can be confusing to know what type of configuration is appropriate for your project.
If you come from a browser Developer Tools background, you might not be used to "launching from your tool," since your browser instance is already open. When you open DevTools, you are simply attaching DevTools to your open browser tab. On the other hand, if you come from a server or desktop background, it's quite normal to have your editor launch your process for you, and your editor automatically attaches its debugger to the newly launched process.
The best way to explain the difference between launch and attach is to think of a launch configuration as a recipe for how to start your app in debug mode before VS Code attaches to it, while an attach configuration is a recipe for how to connect VS Code's debugger to an app or process that's already running.
VS Code debuggers typically support launching a program in debug mode or attaching to an already running program in debug mode. Depending on the request [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
7 or
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
8], different attributes are required, and VS Code's
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
1 validation and suggestions should help with that.
Add a new configuration
To add a new configuration to an existing
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
1, use one of the following techniques:
- Use IntelliSense if your cursor is located inside the configurations array.
- Press the Add Configuration button to invoke snippet IntelliSense at the start of the array.
- Choose Add Configuration option in the Run menu.
VS Code also supports compound launch configurations for starting multiple configurations at the same time; for more details, please read this .
In order to start a debug session, first select the configuration named Launch Program using the Configuration dropdown in the Run and Debug view. Once you have your launch configuration set, start your debug session with F5.
Alternatively, you can run your configuration through the Command Palette [⇧⌘P [Windows, Linux Ctrl+Shift+P]] by filtering on Debug: Select and Start Debugging or typing
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
"args": ["myFolder/path/app.js"],
"windows": {
"args": ["myFolder\\path\\app.js"]
}
}
]
}
1 and selecting the configuration you want to debug.
As soon as a debugging session starts, the DEBUG CONSOLE panel is displayed and shows debugging output, and the Status Bar changes color [orange for default color themes]:
In addition, the debug status appears in the Status Bar showing the active debug configuration. By selecting the debug status, a user can change the active launch configuration and start debugging without needing to open the Run and Debug view.
Debug actions
Once a debug session starts, the Debug toolbar will appear on the top of the editor.
Action Explanation Continue / Pause F5Continue: Resume normal program/script execution [up to the next breakpoint]. Pause: Inspect code executing at the current line and debug line-by-line. Step Over F10Execute the next method as a single command without inspecting or following its component steps. Step Into F11Enter the next method to follow its execution line-by-line. Step Out ⇧F11 [Windows, Linux Shift+F11]When inside a method or subroutine, return to the earlier execution context by completing remaining lines of the current method as though it were a single command. Restart ⇧⌘F5 [Windows, Linux Ctrl+Shift+F5]Terminate the current program execution and start debugging again using the current run configuration. Stop ⇧F5 [Windows, Linux Shift+F5]Terminate the current program execution.
Tip: Use the setting{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "args": ["myFolder/path/app.js"], "windows": { "args": ["myFolder\path\app.js"] } } ] }
2 to control the location of the debug toolbar. It can be the default
{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "args": ["myFolder/path/app.js"], "windows": { "args": ["myFolder\path\app.js"] } } ] }
3,
{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "args": ["myFolder/path/app.js"], "windows": { "args": ["myFolder\path\app.js"] } } ] }
4 to the Run and Debug view, or
{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "args": ["myFolder/path/app.js"], "windows": { "args": ["myFolder\path\app.js"] } } ] }
5. A
3 debug toolbar can be dragged horizontally and also down to the editor area.{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "args": ["myFolder/path/app.js"], "windows": { "args": ["myFolder\path\app.js"] } } ] }
Run mode
In addition to debugging a program, VS Code supports running the program. The Debug: Run [Start Without Debugging] action is triggered with ⌃F5 [Windows, Linux Ctrl+F5] and uses the currently selected launch configuration. Many of the launch configuration attributes are supported in 'Run' mode. VS Code maintains a debug session while the program is running, and pressing the Stop button terminates the program.
Tip: The Run action is always available, but not all debugger extensions support 'Run'. In this case, 'Run' will be the same as 'Debug'.
Breakpoints
Breakpoints can be toggled by clicking on the editor margin or using F9 on the current line. Finer breakpoint control [enable/disable/reapply] can be done in the Run and Debug view's BREAKPOINTS section.
- Breakpoints in the editor margin are normally shown as red filled circles.
- Disabled breakpoints have a filled gray circle.
- When a debugging session starts, breakpoints that cannot be registered with the debugger change to a gray hollow circle. The same might happen if the source is edited while a debug session without live-edit support is running.
If the debugger supports breaking on different kinds of errors or exceptions, those will also be available in the BREAKPOINTS view.
The Reapply All Breakpoints command sets all breakpoints again to their original location. This is helpful if your debug environment is "lazy" and "misplaces" breakpoints in source code that has not yet been executed.
Optionally, breakpoints can be shown in the editor's overview ruler by enabling the setting
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
"args": ["myFolder/path/app.js"],
"windows": {
"args": ["myFolder\\path\\app.js"]
}
}
]
}
7:
Logpoints
A Logpoint is a variant of a breakpoint that does not "break" into the debugger but instead logs a message to the console. Logpoints are especially useful for injecting logging while debugging production servers that cannot be paused or stopped.
A Logpoint is represented by a "diamond" shaped icon. Log messages are plain text but can include expressions to be evaluated within curly braces ['{}'].
Just like regular breakpoints, Logpoints can be enabled or disabled and can also be controlled by a condition and/or hit count.
Note: Logpoints are supported by VS Code's built-in Node.js debugger, but can be implemented by other debug extensions. The Python and Java extensions, for example, support Logpoints.
Data inspection
Variables can be inspected in the VARIABLES section of the Run and Debug view or by hovering over their source in the editor. Variable values and expression evaluation are relative to the selected stack frame in the CALL STACK section.
Variable values can be modified with the Set Value action from the variable's context menu. Additionally, you can use the Copy Value action to copy the variable's value, or Copy as Expression action to copy an expression to access the variable.
Variables and expressions can also be evaluated and watched in the Run and Debug view's WATCH section.
Variable names and values can be filtered by typing while the focus is on the VARIABLES section.
Launch.json attributes
There are many
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"args": ["${env:USERNAME}"]
}
1 attributes to help support different debuggers and debugging scenarios. As mentioned above, you can use IntelliSense [⌃Space [Windows, Linux Ctrl+Space]] to see the list of available attributes once you have specified a value for the
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
"args": ["myFolder/path/app.js"],
"windows": {
"args": ["myFolder\\path\\app.js"]
}
}
]
}
9 attribute.
The following attributes are mandatory for every launch configuration:
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "args": ["myFolder/path/app.js"], "windows": { "args": ["myFolder\\path\\app.js"] } }9 - the type of debugger to use for this launch configuration. Every installed debug extension introduces a type:
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }1 for the built-in Node debugger, for example, or
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }2 and
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }4 - the request type of this launch configuration. Currently,
{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/app.js", "cwd": "${workspaceFolder}", "args": ["${env:USERNAME}"] }
8 and
{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/app.js", "cwd": "${workspaceFolder}", "args": ["${env:USERNAME}"] }
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }
Here are some optional attributes available to all launch configurations:
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }8 - using the
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }9,
"launch": {
}"version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${file}" }]0, and
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "args": ["myFolder/path/app.js"], "windows": { "args": ["myFolder\\path\\app.js"] } }5 attributes in the
{ "version": "0.2.0", "configurations": [
] }{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js", "stopOnEntry": true, "osx": { "stopOnEntry": false } }"launch": {
}"version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${file}" }]3 - to launch a task before the start of a debug session, set this attribute to the label of a task specified in tasks.json [in the workspace's
{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/app.js", "cwd": "${workspaceFolder}", "args": ["${env:USERNAME}"] }
3 folder]. Or, this can be set to
"launch": {
}"version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${file}" }]"launch": {
}"version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${file}" }]6 - to launch a task at the very end of a debug session, set this attribute to the name of a task specified in tasks.json [in the workspace's
{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/app.js", "cwd": "${workspaceFolder}", "args": ["${env:USERNAME}"] }
"launch": {
}"version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${file}" }]"launch": {
}"version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Launch Program", "program": "${file}" }]{ "name": "launch program that reads a file from stdin", "type": "node", "request": "launch", "program": "program.js", "console": "integratedTerminal", "args": ["