John Lancaster
109 lines
3.3 KiB
Markdown
109 lines
3.3 KiB
Markdown
# 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.
|