# Debug Launch Configurations in VS Code

This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`.

## Core Structure

A minimal launch file:

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

Useful fields for Python configs:

- `type`: Use `debugpy`.
- `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.
- `env` / `envFile`: Environment variables.
- `console`: `integratedTerminal` is usually most practical.
- `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:

```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.

## 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.