How to Pass Arguments and Environment Variables to a VS Code Debugger

Your program often needs command-line arguments and environment variables to run correctly. You can set both directly in your launch configuration instead of typing them manually before each debug session.

Pass command-line arguments with args

Add an args array to any launch configuration. Each argument is a separate string, exactly as it would appear on the command line.

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch with Args",
  "program": "${workspaceFolder}/server.js",
  "args": ["--port", "3000", "--env", "staging"]
}

When VS Code launches the program, it appends these arguments after the program path. The program receives them through the normal argument parsing mechanism: process.argv in Node.js, sys.argv in Python, os.Args in Go.

Arguments can include flags, values, file paths, or any other string your program expects. Use the workspace folder variable for paths:

json

"args": ["--config", "${workspaceFolder}/config/app.yaml"]

Set environment variables with env

Add an env object to set environment variables for the debugged process. Each key is a variable name and each value is a string.

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch with Env",
  "program": "${workspaceFolder}/server.js",
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug",
    "DATABASE_URL": "postgres://localhost:5432/myapp"
  }
}

These variables are set only for the debugged program. They do not affect your terminal, other VS Code sessions, or the system environment.

In your code, read them the standard way: process.env.NODE_ENV in Node.js, os.environ["NODE_ENV"] in Python, os.Getenv("NODE_ENV") in Go.

Reference existing shell variables

If an environment variable already exists in your shell, reference it instead of duplicating its value. Use the env variable syntax with the NAME pattern inside any string field.

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch with Shell Env",
  "program": "${workspaceFolder}/server.js",
  "env": {
    "API_KEY": "${env:MY_API_KEY}",
    "DEPLOY_ENV": "${env:DEPLOY_ENV}"
  }
}

VS Code reads MY_API_KEY and DEPLOY_ENV from your shell environment at debug time and passes them to the program. This keeps secrets out of your configuration file, which you may commit to version control.

You can also use shell variables directly in args:

json

"args": ["--token", "${env:CI_TOKEN}"]

Platform-specific arguments and variables

Different operating systems may need different arguments or environment values. Use the windows, linux, and osx blocks to override settings per platform. Each block can contain its own args or env values.

json

{
  "type": "node",
  "request": "launch",
  "name": "Cross-Platform Launch",
  "program": "${workspaceFolder}/server.js",
  "args": ["--port", "3000"],
  "windows": {
    "args": ["--port", "3000", "--use-win-crypto"]
  }
}

VS Code applies the platform-specific block that matches your operating system, overriding the matching top-level keys. Keys not listed in the platform block keep their top-level values.

Use VS Code predefined variables

You can use VS Code's built-in variables in args and env values. These resolve at debug time to paths, file names, and other context.

Common variables for arguments and environment:

• The workspace root path: useful for file paths in args
• The active file: pass the current editor file to a script
• The active file name without extension: use as a module name
• Configuration settings: reference a VS Code setting value

For a full list, see the variables reference. You can also use input variables with the ${input:variableID} syntax to prompt for a value before each debug session.

Troubleshooting

My program does not see the environment variable

Check that the variable is in the env object of the correct configuration. The Run and Debug dropdown shows which configuration is active. Also check that your code reads the variable correctly. In Node.js, use process.env.VAR_NAME, not just VAR_NAME.

The args are not passed to my program

The args array is only available for launch configurations. Attach configurations connect to an already-running process and cannot pass new arguments. If you need to change arguments, stop the process, update the launch configuration, and start again.

A shell variable reference is empty

The environment variable may not be set in your shell. Open a terminal outside VS Code and run echo $VARIABLE_NAME (macOS/Linux) or echo %VARIABLE_NAME% (Windows) to verify. If the variable is set in a shell profile that only runs for login shells, VS Code may not see it. Set the variable in your system environment or in a file that runs for non-login shells.