John Lancaster
102 lines
2.3 KiB
Markdown
102 lines
2.3 KiB
Markdown
# 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.
|