How to Create and Configure launch.json in VS Code

When you press F5 to debug, VS Code needs to know how to start your program. For simple single-file programs, VS Code guesses correctly. For anything else, you need a launch.json file.

A launch.json file is a JSON configuration that tells VS Code which debugger to use, which file to run, what arguments to pass, and what environment variables to set. It lives in the .vscode folder at the root of your workspace.

Create launch.json

Open the Run and Debug view (Ctrl+Shift+D / Cmd+Shift+D). If no configuration exists, the dropdown at the top shows No Configurations. Click create a launch.json file.

VS Code shows a list of environments: Node.js, Python, Chrome, Go, C++, and others. The list changes depending on which debugger extensions you have installed. Pick the one that matches your project.

VS Code generates a launch.json file and opens it in the editor. It creates a .vscode folder if one does not already exist. The generated file contains one or more pre-filled configurations that you can edit.

If your language is not in the list, choose Node.js as a starting point. You can change the type field later after installing the correct debugger extension.

The anatomy of a launch configuration

A minimal launch.json looks like this:

json

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

Every field serves a specific purpose:

• version: The format version. Keep it as 0.2.0.
• configurations: An array of configuration objects. You can have as many as you need, each with a unique name.
• type: The debugger type. This matches the debugger extension: node, python, go, cppdbg, php, chrome, and others.
• request: Either launch (start the program and attach the debugger) or attach (connect to an already-running program).
• name: The label shown in the Run and Debug dropdown. Make it descriptive. With multiple configurations, names like "Launch Server" and "Launch Client" help tell them apart.
• program: The path to the file the debugger should run. Use the workspace folder variable to keep it relative to your project root.

Essential configuration fields

Beyond the basics, these fields cover most real-world needs.

args

Pass command-line arguments to your program. Each argument is a separate string in an array.

json

"args": ["--port", "3000", "--env", "development"]

Each argument is a separate string in the array. The debugged program receives these arguments as if you typed them on the command line. This is the same as running the program with those flags in a terminal.

env

Set environment variables for the debugged process. Each key is a variable name and each value is a string. These settings only affect the debugged program and do not leak into your terminal or other VS Code sessions.

json

"env": {
  "NODE_ENV": "development",
  "DEBUG": "myapp:*"
}

If you need to reference an existing environment variable from your shell, use the env variable syntax inside any string field. For example, the args field can read API_TOKEN from your shell environment at debug time. Never write secrets directly into this file.

cwd

Set the current working directory for the debugged program. By default, it is the workspace root. Change it if your program expects to run from a subfolder. For example, setting cwd to ${workspaceFolder}/server makes the server subfolder the working directory during debugging.

console

Controls where program output appears. For Node.js, use internalConsole for the Debug Console (the default) or integratedTerminal for the VS Code terminal. Choose integratedTerminal if your program reads from stdin. Set it with a line like "console": "integratedTerminal" in your configuration.

preLaunchTask

Run a task before the debugger starts. Use this to compile TypeScript, build a binary, or start a dependency server. The value must match a task label from your tasks file. The debugger waits for the task to finish before starting.

json

"preLaunchTask": "npm: build"

For more about tasks, see the tasks.json guide.

Real configuration examples

Here are complete working configurations for common project types. Each one is ready to copy into your own file. Change the program path and name to match your project.

Node.js application with a custom entry point

This configuration launches a Node.js server with a custom port, development environment variables, and terminal output so you can see logs and interact with stdin.

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch Server",
  "program": "${workspaceFolder}/src/index.js",
  "args": ["--port", "8080"],
  "env": {
    "NODE_ENV": "development"
  },
  "console": "integratedTerminal"
}

Python file with the current interpreter

This configuration runs whichever Python file is currently open in the editor. VS Code uses the Python interpreter you selected for the workspace.

json

{
  "type": "debugpy",
  "request": "launch",
  "name": "Python: Current File",
  "program": "${file}"
}

Using the file variable is convenient when you switch between scripts often. You do not need to create a separate configuration for each Python file.

TypeScript with a compile step first

This configuration compiles TypeScript before debugging. The preLaunchTask runs the TypeScript compiler, and outFiles tells the debugger where to find the generated JavaScript.

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch TS",
  "program": "${workspaceFolder}/src/app.ts",
  "preLaunchTask": "tsc: build - tsconfig.json",
  "outFiles": ["${workspaceFolder}/dist/**/*.js"]
}

The outFiles field is critical for TypeScript debugging. Without it, breakpoints set in your .ts files will not map to the running .js output, and the debugger will skip them.

Attach to a running process

This configuration does not start anything. It connects the debugger to a Node.js process that is already running elsewhere, such as a server you started from the terminal.

json

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Process",
  "processId": "${command:pickProcess}"
}

This configuration does not start anything. It lets you pick a running Node.js process from a list and attach the debugger to it. Use this when you started the server from a terminal and want to debug it without restarting.

VS Code variables in launch.json

VS Code supports predefined variables inside configuration strings. These keep your configuration portable across machines.

text

${workspaceFolder}           root folder of your open workspace
${file}                      currently active file in the editor
${fileBasenameNoExtension}   active file name without the extension
${relativeFile}              active file path relative to the workspace root
${cwd}                       working directory when VS Code started
${env:NAME}                  value of the NAME environment variable
${config:editor.fontSize}    value of a VS Code setting

Use these instead of a hardcoded absolute path so the same launch.json works on every teammate's machine.

You can also use the input variable syntax to prompt the user for a value before debugging starts. Configure the input in an inputs section of the configuration file.

Switch between configurations

Once you have multiple configurations, the dropdown at the top of the Run and Debug view lists them by their name field. Select one and press F5 to start debugging with that configuration.

You can also click the debug status in the Status Bar to switch configurations without opening the Run and Debug view.

Troubleshooting

The dropdown still says No Configurations

The configuration file must be in the .vscode folder at the workspace root, and it must be valid JSON. A missing comma, trailing comma, or unquoted key breaks the file. VS Code shows a warning icon in the editor gutter if the JSON is invalid.

"Cannot find runtime" or "Debugger type not recognized"

The type field must match a debugger extension you have installed. Check the Extensions view to confirm the debugger is installed and enabled. If you changed the type manually, make sure the spelling is correct.

My preLaunchTask never runs

The task must exist in your tasks file and its label must match exactly. Open the Command Palette and run Tasks: Run Task. If your task does not appear, create it first or let VS Code auto-detect it.

Breakpoints do not work in compiled code

If you compile TypeScript, JavaScript, or another language, the debugger needs to map your source files to the running output. Add outFiles to your configuration pointing to the compiled directory, or enable source maps in your compiler settings.

With your configuration in place, the next step is to learn how breakpoints, conditional breakpoints, and logpoints pause your code at the right moment.