# Debug Launch Configurations in VS Code

This reference focuses on Python debugging through [`debugpy`](https://github.com/microsoft/debugpy) using [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration).

## Core Structure

A minimal launch file:

```json
{
  "version": "0.2.0",
  "configurations": []
}
```

Useful fields for Python configs:

- `type`: Use [`debugpy`](https://code.visualstudio.com/docs/python/debugging).
- `request`: Usually `launch`, sometimes `attach`.
- `name`: Friendly profile name shown in the Run and Debug panel.
- `program`: Script path for script-based entry.
- `module`: Module name for `python -m ...` style launches.
- `args`: CLI arguments.
- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)).
- `env` / `envFile`: Environment variables (commonly from [environment variable definitions files](https://code.visualstudio.com/docs/python/environments#_environment-variable-definitions-file)).
- `console`: `integratedTerminal` is usually most practical ([launch options](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes)).
- `justMyCode`: `true` by default; set `false` when stepping into dependencies.

## Launch vs Attach

Use `launch` when VS Code should start the process.
Use `attach` when the process already runs with debugpy listening.

Attach profile example:

```json
{
  "name": "Python: Attach (debugpy :5678)",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "127.0.0.1",
    "port": 5678
  },
  "justMyCode": true
}
```

Remote process side command example (from [debugpy CLI usage](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging)):

```bash
python -m debugpy --listen 5678 -m your_package.main
```

## Script and Module Patterns

Script pattern:

```json
{
  "name": "Python: Script",
  "type": "debugpy",
  "request": "launch",
  "program": "${workspaceFolder}/src/app.py",
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal",
  "justMyCode": true
}
```

Module pattern:

```json
{
  "name": "Python: Module",
  "type": "debugpy",
  "request": "launch",
  "module": "your_package.main",
  "cwd": "${workspaceFolder}",
  "console": "integratedTerminal",
  "justMyCode": true
}
```

Prefer module mode when imports depend on package layout.

## Environment and Interpreter Notes

- Use `envFile` for shared local variables, commonly `${workspaceFolder}/.env`.
- Keep secrets out of committed launch configs.
- Ensure the selected VS Code interpreter matches project tooling.

## Source Documentation

- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging)
- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)
- [Variables reference](https://code.visualstudio.com/docs/editor/variables-reference)
- [debugpy project](https://github.com/microsoft/debugpy)

## Troubleshooting

If breakpoints do not hit:

1. Confirm the right profile is selected.
2. Confirm the file path/module path is correct.
3. Disable `justMyCode` temporarily to inspect call flow.
4. Confirm no stale background process is occupying the expected port.
5. Confirm workspace root and `cwd` align with imports.