Skip to content

HezaoHezao/poirot / poirot/backend/agents/skill/builtin_skills/software-development/python-debugpy

python-debugpy

Unverified

Debug Python: pdb REPL + debugpy remote (DAP).

Python Debugger (pdb + debugpy)

Overview

Three tools, picked by situation:

ToolWhen
breakpoint() + pdbLocal, interactive, simplest. Add breakpoint() in source, run, get REPL.
python -m pdbLaunch script under pdb with no source edits.
debugpyRemote / headless / attach to running process. DAP, scriptable.

Start with breakpoint(). It's the cheapest thing that works.

When to Use

  • A test fails and the traceback doesn't reveal why a value is wrong
  • You need to step through a function and watch a collection mutate
  • A long-running process misbehaves and you can't restart it
  • Post-mortem: an exception fired and you want to inspect locals at crash site
  • A subprocess is the actual bug site

Don't use for: things print() / logging.debug solve in under a minute, or things pytest -vv --tb=long --showlocals already reveals.

pdb Quick Reference

Inside any pdb prompt ((Pdb)):

CommandAction
h / h cmdhelp
nnext line (step over)
sstep into
rreturn from current function
ccontinue
unt Ncontinue until line N
j Njump to line N (same function only)
b Nset breakpoint at line N
b file:Nset breakpoint in another file
b funcset breakpoint at function
cl Nclear breakpoint N
llist 11 lines around current
lllist whole function
w / whereshow call stack
u / dmove up/down stack frame
p exprprint expression
pp exprpretty-print expression
aprint args of current function
argssame as a
display exprwatch expression (re-eval each step)
interactdrop into interactive Python REPL

Using breakpoint()

def process(data):
    result = transform(data)
    breakpoint()  # Execution pauses here, pdb REPL opens
    return result

Run normally:

python script.py
# Pauses at breakpoint(), (Pdb) prompt appears

Using python -m pdb (no source edits)

python -m pdb script.py
# Starts paused at first line

Post-mortem debugging

Drop into pdb at the exact exception site:

import pdb, traceback
try:
    main()
except Exception:
    traceback.print_exc()
    pdb.post_mortem()

Or:

python -m pdb -c continue script.py
# Runs until exception, then drops to pdb at the crash

debugpy (remote attach)

For long-running processes or headless debugging:

# Install
pip install debugpy

# Option 1: Launch with debugpy
python -m debugpy --listen 5678 --wait-for-client script.py

# Option 2: Inject into running code
import debugpy
debugpy.listen(5678)
print("Waiting for debugger on port 5678...")
debugpy.wait_for_client()

Attach from another terminal (DAP client):

# Using debugpy's CLI to set breakpoints + continue
python -m debugpy --connect localhost:5678 --set-breakpoint script.py:42

Or use any DAP-compatible editor (VS Code, Neovim) to attach to port 5678.

Common Debugging Patterns

Watch a variable change

# In pdb
(Pdb) display my_list
# Each step, pdb re-evaluates and shows the value if changed

Conditional breakpoint

# In source
breakpoint() if condition else None

# Or in pdb
(Pdb) b 42, x > 100  # Break at line 42 only when x > 100

Inspect a running subprocess

import debugpy
# In the subprocess code:
debugpy.listen(5679)
debugpy.wait_for_client()
# Parent can attach to port 5679

Pitfalls

  • breakpoint() in production: remove before commit. Use breakpoint() only for local debugging.
  • pdb + multiprocessing: child processes don't inherit the pdb prompt. Use debugpy for multi-process debugging.
  • pdb + asyncio: pdb works but async stack traces can be confusing. Use w (where) to see the full async call stack.
  • Windows + pdb: some pdb features work differently on Windows. python -m pdb is more reliable than breakpoint() in some Windows terminals.
  • debugpy port conflicts: default port 5678 may be taken. Use --listen 5679.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall