| name | python-debugpy |
| description | Python debugging with pdb, debugpy, and remote attach |
| alwaysInclude | false |
| requiredBins | ["python3"] |
| platforms | ["darwin","linux"] |
| version | 1.0.0 |
| tenantIds | [] |
Python Debugging
Debug Python applications using pdb (built-in), debugpy (VS Code protocol), and remote attach workflows. Covers breakpoints, post-mortem debugging, and profiling.
pdb — Built-in Debugger
Launching
python3 -m pdb script.py
python3 -c "
import mymodule
try:
mymodule.run()
except Exception:
import pdb; pdb.post_mortem()
"
Inline Breakpoints
breakpoint()
import pdb; pdb.set_trace()
Key Commands
| Command | Action |
|---|
n / next | Step over |
s / step | Step into |
c / continue | Continue execution |
r / return | Continue until function returns |
l / list | Show source around current line |
ll | Show full source of current function |
p expr | Print expression value |
pp expr | Pretty-print expression value |
w / where | Print stack trace |
u / up | Move up one frame |
d / down | Move down one frame |
b file:line | Set breakpoint |
cl num | Clear breakpoint |
commands num | Set commands to run at breakpoint |
interact | Start interactive interpreter in current frame |
Conditional Breakpoints
import pdb; pdb.set_trace() if len(items) > 100 else None
debugpy — Remote Debugging
Install
pip install debugpy
Launch Modes
python3 -m debugpy --listen 0.0.0.0:5678 --wait-for-client script.py
python3 -m debugpy --listen 5678 script.py
python3 -m debugpy --listen 5678 --pid 12345
Programmatic Setup
import debugpy
debugpy.listen(("0.0.0.0", 5678))
print("Waiting for debugger attach...")
debugpy.wait_for_client()
debugpy.breakpoint()
main()
Remote Attach via DAP
Connect any DAP-compatible client to the debug server:
{
"type": "debugpy",
"request": "attach",
"connect": { "host": "localhost", "port": 5678 },
"pathMappings": [
{ "localRoot": "${workspaceFolder}", "remoteRoot": "/app" }
]
}
Profiling
cProfile
python3 -m cProfile -s cumulative script.py
python3 -m cProfile -o profile.stats script.py
python3 -c "
import pstats
p = pstats.Stats('profile.stats')
p.sort_stats('cumulative')
p.print_stats(20)
"
line_profiler
pip install line_profiler
kernprof -l -v script.py
memory_profiler
pip install memory_profiler
python3 -m memory_profiler script.py
Common Patterns
Debug Django
python3 -m debugpy --listen 5678 manage.py runserver --noreload
Debug pytest
python3 -m pytest --pdb
python3 -m pytest -x --pdb
python3 -m debugpy --listen 5678 -m pytest tests/
Debug in Docker
# Expose debug port
EXPOSE 5678
CMD ["python3", "-m", "debugpy", "--listen", "0.0.0.0:5678", "app.py"]
Rules
- Use
breakpoint() over import pdb; pdb.set_trace() for Python 3.7+.
- Use
--wait-for-client when you need to debug startup code.
- Use
--noreload with Django to avoid debugger disconnects on file changes.
- Profile first — use cProfile before reaching for a debugger on performance issues.
- Check
PYTHONBREAKPOINT env var — it controls what breakpoint() calls.