prompts/docs/skills/vscode-configuration/references/debug-launch-configurations.md

Debug Launch Configurations in VS Code

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

Core Structure

A minimal launch file:

{
  "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:

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

Remote process side command example:

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

Script and Module Patterns

Script pattern:

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

Module pattern:

{
  "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.