Python Debugpy
Debug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Python Debugpy when an AI agent needs a reusable SKILL.md workflow for this job: Debug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
When not to use it
Skip Python Debugpy when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/python-debugpy # Save SKILL.md to ~/.claude/skills/python-debugpy/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/python-debugpy/SKILL.md. For a shared project, commit the folder at .claude/skills/python-debugpy/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Python Debugpy skill for this task: Use Python Debugpy when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
68/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 68/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Python Debugpy
Use when Python code needs interactive debugging: hidden locals, confusing state mutation, failing tests, subprocesses, long-running services, or remote/headless attach.
Pick the smallest debugger that reaches the bad frame.
## Choose
- `breakpoint()`: local code, source edits ok, fastest path. - `python3 -m pdb`: no source edit, launch from the beginning. - `python3 -m pdb -c continue`: stop at an unhandled exception. - `debugpy`: remote/headless process, DAP client, already-running PID, or service startup race.
## Commands
```bash python3 -m pdb path/to/script.py arg1 python3 -m pdb -c continue path/to/script.py python3 -c "import debugpy" || python3 -m pip install debugpy python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client path/to/script.py python3 -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m package.module python3 -m debugpy --listen 127.0.0.1:5678 --pid <pid> ```
For source-edit attach:
```py import debugpy
debugpy.listen(("127.0.0.1", 5678)) debugpy.wait_for_client() debugpy.breakpoint() ```
For post-mortem:
```py import pdb, sys
try: run() except Exception: pdb.post_mortem(sys.exc_info()[2]) raise ```
## pdb
- Flow: `n`, `s`, `r`, `c`, `q`. - Stack/source: `w`, `u`, `d`, `a`, `l`, `ll`. - Values: `p expr`, `pp expr`, `display expr`. - Breakpoints: `b file.py:42`, `b func`, `b file.py:42, condition`, `cl <num>`. - Mutate/evaluate: `!statement`; full REPL: `interact`.
## Rules
- Reproduce with the smallest command/test first. - Disable parallel test workers for pdb; interactive stdin usually breaks inside worker pools. - Keep `debugpy` in the active env; do not add it as a project dependency unless the project already wants it. - Bind debug servers to `127.0.0.1`; do not expose `0.0.0.0` unless isolated or tunnelled. - Use unique ports for parallel sessions. - `debugpy --pid` injects into a running process; confirm the target pid before attaching. - If PID attach fails on Linux, check ptrace/container privileges before changing the target. - Cleanup before commit: `rg -n 'breakpoint\\(|pdb\\.set_trace|debugpy\\.' --type py`. - Rerun the normal project test/gate without the debugger. - `PYTHONBREAKPOINT=0` disables `breakpoint()`. - If a process is stuck after debugger detach, confirm it is not still paused at a breakpoint.
Intended uses
- Use Python Debugpy when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.