← 返回首页
Visual Studio Code debug configuration
Visual Studio Code
Download

Use the Agents window to build in an agent-first way.

Documentation

Topics Overview Overview Linux macOS Windows VS Code for the Web Raspberry Pi Network Additional Components Uninstall VS Code Tutorial Copilot Quickstart User Interface Personalize VS Code Install Extensions Tips and Tricks Intro Videos Overview Setup Quickstart Overview Language Models Context Tools Agents Customization Trust & Safety Overview Agents Tutorial Agents Window Planning Memory Tools Subagents Local Agents Copilot CLI Cloud Agents Third-Party Agents Overview Chat Sessions Add Context Inline Chat Review Edits Checkpoints Artifacts Panel Debug Chat Interactions Prompt Examples Overview Instructions Prompt Files Custom Agents Agent Skills Language Models MCP Hooks Plugins Context Engineering Customize AI Test-Driven Development Edit Notebooks with AI Test with AI Test Web Apps with Browser Tools Debug with AI MCP Dev Guide OpenTelemetry Monitoring Inline Suggestions Smart Actions Best Practices Security Troubleshooting FAQ Cheat Sheet Settings Reference MCP Configuration Workspace Context Display Language Layout Keyboard Shortcuts Settings Settings Sync Extension Marketplace Extension Runtime Security Themes Profiles Overview Voice Interactions Command Line Interface Telemetry Basic Editing IntelliSense Code Navigation Refactoring Snippets Overview Multi-Root Workspaces Workspace Trust Tasks Debugging Debug Configuration Testing Port Forwarding Integrated Browser Overview Quickstart Staging & Committing Branches & Worktrees Repositories & Remotes Merge Conflicts Collaborate on GitHub Troubleshooting FAQ Getting Started Tutorial Terminal Basics Terminal Profiles Shell Integration Appearance Advanced Overview Enterprise Policies AI Settings Extensions Telemetry Updates Overview JavaScript JSON HTML Emmet CSS, SCSS and Less TypeScript Markdown PowerShell C++ Java PHP Python Julia R Ruby Rust Go T-SQL C# .NET Swift Working with JavaScript Node.js Tutorial Node.js Debugging Deploy Node.js Apps Browser Debugging Angular Tutorial React Tutorial Vue Tutorial Debugging Recipes Performance Profiling Extensions Tutorial Transpiling Editing Refactoring Debugging Quick Start Tutorial Run Python Code Editing Linting Formatting Debugging Environments Testing Python Interactive Django Tutorial FastAPI Tutorial Flask Tutorial Create Containers Deploy Python Apps Python in the Web Settings Reference Getting Started Navigate and Edit Refactoring Formatting and Linting Project Management Build Tools Run and Debug Testing Spring Boot Modernizing Java Apps Application Servers Deploy Java Apps GUI Applications Extensions FAQ Intro Videos GCC on Linux GCC on Windows GCC on Windows Subsystem for Linux Clang on macOS Microsoft C++ on Windows Build with CMake CMake Tools on Linux CMake Quick Start C++ Dev Tools for Copilot Editing and Navigating Debugging Configure Debugging Refactoring Settings Reference Configure IntelliSense Configure IntelliSense for Cross-Compiling FAQ Intro Videos Get Started Navigate and Edit IntelliCode Refactoring Formatting and Linting Project Management Build Tools Package Management Run and Debug Testing FAQ Overview Node.js Python ASP.NET Core Debug Docker Compose Registries Deploy to Azure Choose a Dev Environment Customize Develop with Kubernetes Tips and Tricks Overview Jupyter Notebooks Data Science Tutorial Python Interactive Data Wrangler Quick Start Data Wrangler PyTorch Support Azure Machine Learning Manage Jupyter Kernels Jupyter Notebooks on the Web Data Science in Microsoft Fabric Foundry Toolkit Overview Foundry Toolkit Copilot Tools Create Agents Models Playground Agent Builder Agent Inspector Evaluation Tool Catalog Fine-Tuning (Automated Setup) Fine-Tuning (Project Template) Model Conversion Tracing Profiling (Windows ML) FAQ File Structure Manual Model Conversion Manual Model Conversion on GPU Setup Environment Without Foundry Toolkit Template Project Migrating from Visualizer to Agent Inspector Overview Getting Started Resources View Deployment VS Code for the Web - Azure Containers Azure Kubernetes Service Kubernetes MongoDB Remote Debugging for Node.js Overview SSH Dev Containers Windows Subsystem for Linux GitHub Codespaces VS Code Server Tunnels SSH Tutorial WSL Tutorial Tips and Tricks FAQ Overview Tutorial Attach to Container Create Dev Container Advanced Containers devcontainer.json Dev Container CLI Tips and Tricks FAQ Default Keyboard Shortcuts Default Settings Substitution Variables Tasks Schema
Copy as Markdown

On this page there are 12 sections

Visual Studio Code debug configuration

For complex debugging scenarios or applications, you need to create a launch.json file to specify the debugger configuration. For example, to specify the application entry point, attach to a running application, or to set environment variables.

To learn more about debugging in VS Code, see Debugging in Visual Studio Code.

Tip

Copilot in VS Code can help you create a launch configuration for your project. Get more info about generating a launch configuration with Copilot.

Launch configurations

For simple applications or debugging scenarios, you can run and debug a program without specific debugging configurations. Use the F5 key and VS Code will try to run your currently active file.

However, for most debugging scenarios you need to create a debugging configuration (launch configuration). For example, to specify the application entry point, attach to a running application, or set environment variables. Creating a launch configuration file is also beneficial because it allows you to configure and save debugging setup details with your project.

VS Code stores debugging configuration information in a launch.json file located in the .vscode folder in your workspace (project root folder), or in your user settings or workspace settings.

The following snippet describes a sample configuration for debugging a Node.js application:

/**"], "program": "${workspaceFolder}\\app.js" } ] }

VS Code also supports compound launch configurations for starting multiple configurations at the same time.

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.

Create a debug configuration file

To create an initial launch.json file:

  1. Select create a launch.json file in the Run and Debug view.

  2. VS Code tries to detect your debug environment. If it's unable to do so, you can choose it manually:

    Based on the selected debug environment, VS Code creates a starter configuration in the launch.json file.

  3. In the Explorer view (⇧⌘E (Windows, Linux Ctrl+Shift+E)), notice that VS Code created a .vscode folder and added the launch.json file to your workspace.

You can now edit the launch.json file to add more configurations or modify existing ones.

Add a configuration to launch.json

To add a new configuration to an existing launch.json, use one of the following techniques:

  • Press the Add Configuration button and then select a snippet to add a predefined configuration.
  • Use IntelliSense if your cursor is located inside the configurations array.
  • Choose the Run > Add Configuration menu option.

Generate a launch configuration with AI

With Copilot in VS Code, you can accelerate the process of creating a launch configuration for your project. To generate a launch configuration with Copilot:

  1. Open the Chat view with ⌃⌘I (Windows, Linux Ctrl+Alt+I), or select Open Chat from the Copilot menu in the title bar.

  2. Enter the /startDebugging chat prompt to generate a debug configuration.

    Alternatively, you can also enter a custom prompt, like generate a debug config for an express app #codebase.

    This can be useful if your workspace has files with different languages.

    Note

    The #codebase chat variable gives Copilot the context of your project, which helps it generate a more accurate response.

  3. Apply the suggested configuration, and then start debugging.

Start a debugging session with a launch configuration

To start a debug session with a launch configuration:

  1. Select the configuration named Launch Program using the Configuration dropdown in the Run and Debug view.

    The list of available configurations matches those in the launch.json file.

  2. Start your debug session with F5 or select Start Debugging (play icon) in Run and Debug view.

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 'debug ' and selecting the configuration you want to debug.

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 (attach or launch), different attributes are required, and VS Code's launch.json validation and suggestions should help with that.

Launch.json attributes

There are many launch.json attributes to help support different debuggers and debugging scenarios. You can use IntelliSense (⌃Space (Windows, Linux Ctrl+Space)) to see the list of available attributes once you have specified a value for the type attribute. The attributes available in launch configurations vary from debugger to debugger.

An attribute that is available for one debugger doesn't automatically work for other debuggers too. If you see red squiggles in your launch configuration, hover over them to learn what the problem is and try to fix them before launching a debug session.

The following attributes are mandatory for every launch configuration:

  • type - the type of debugger to use for this launch configuration. Every installed debug extension introduces a type: node for the built-in Node debugger, for example, or php and go for the PHP and Go extensions.
  • request - the request type of this launch configuration. Currently, launch Open in VS Code Open in VS Code Insiders and attach are supported.
  • name - the reader-friendly name to appear in the Debug launch configuration dropdown.

Here are some optional attributes available to all launch configurations:

  • presentation - using the order, group, and hidden attributes in the presentation object, you can sort, group, and hide configurations and compounds in the Debug configuration dropdown and in the Debug quick pick. You can also set presentation inside platform-specific sections (windows, linux, osx) to control visibility per operating system.
  • preLaunchTask - 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 .vscode folder). Or, this can be set to ${defaultBuildTask} to use your default build task.
  • postDebugTask - 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 .vscode folder).
  • internalConsoleOptions - this attribute controls the visibility of the Debug console panel during a debugging session.
  • debugServer - for debug extension authors only: this attribute allows you to connect to a specified port instead of launching the debug adapter.
  • serverReadyAction - if you want to open a URL in a web browser whenever the program under debugging outputs a specific message to the debug console or integrated terminal. For details see section Automatically open a URI when debugging a server program below.

Many debuggers support some of the following attributes:

  • program - executable or file to run when launching the debugger
  • args - arguments passed to the program to debug
  • env - environment variables (the value null can be used to "undefine" a variable)
  • envFile - path to dotenv file with environment variables
  • cwd - current working directory for finding dependencies and other files
  • port - port when attaching to a running process
  • stopOnEntry - break immediately when the program launches
  • console - what kind of console to use, for example, internalConsole, integratedTerminal, or externalTerminal

Variable substitution

VS Code makes commonly used paths and other values available as variables and supports variable substitution inside strings in launch.json. This means that you do not have to use absolute paths in debug configurations. For example, ${workspaceFolder} gives the root path of a workspace folder, ${file} the file open in the active editor, and ${env:Name} the environment variable 'Name'.

You can see a full list of predefined variables in the Variables Reference or by invoking IntelliSense inside the launch.json string attributes.

{ "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"] } } ] }

Valid operating system properties are "windows" for Windows, "linux" for Linux, and "osx" for macOS. Properties defined in an operating system specific scope override properties defined in the global scope.

The type property cannot be placed inside a platform-specific section because type indirectly determines the platform in remote debugging scenarios, which would result in a cyclic dependency.

In the following example, debugging the program always stops on entry, except on macOS:

{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/app.js", "osx": { "presentation": { "hidden": true } } } ] }

Global launch configuration

You can define launch configurations that are available across all your workspaces. To specify a global launch configuration, add a launch configuration object in your launch Open in VS Code Open in VS Code Insiders user setting. This launch configuration is then shared across your workspaces. For example:

{ "name": "launch program that reads a file from stdin", "type": "node", "request": "launch", "program": "program.js", "console": "integratedTerminal", "args": ["<", "in.txt"] }

This approach requires that the < syntax is passed through the debugger extension and ends up unmodified in the Integrated Terminal.

Compound launch configurations

An alternative way to start multiple debug sessions is by using a compound launch configuration. You can define compound launch configurations in the compounds property in the launch.json file.

Use the configurations attribute to list the names of two or more launch configurations that should be launched in parallel.

Optionally, specify a preLaunchTask task that is run before the individual debug sessions are started. The boolean flag stopAll controls whether manually terminating one session stops all of the compound sessions.

var express = require('express'); var app = express(); app.get('/', function(req, res) { res.send('Hello World!'); }); app.listen(3000, function() { console.log('Example app listening on port 3000!'); });

This application first installs a "Hello World" handler for the "/" URL and then starts to listen for HTTP connections on port 3000. The port is announced in the Debug Console, and typically, the developer would now type http://localhost:3000 into their browser application.

The serverReadyAction feature makes it possible to add a structured property serverReadyAction to any launch config and select an "action" to be performed: