python-debugpy

Debug Python code using pdb breakpoints, post-mortem inspection, and debugpy remote attach.

Updated Jul 10, 2026
One-click install
npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill python-debugpy-avatar-arts
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: python-debugpy
Source: https://github.com/AvaTar-ArTs/.Agent-skills/tree/main/skills/software-development/python-debugpy
Command: npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill python-debugpy-avatar-arts

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires debugpy, remote-pdb.

What problem does it solve? Diagnosing why Python code fails is hard when tracebacks alone don't reveal wrong values, and long-running processes like gateways or daemons can't simply be restarted to add print statements. This Skill provides structured recipes for interactive debugging with pdb, post-mortem exception inspection, and remote debugging of running processes via debugpy or remote-pdb. ## Core Features & Use Cases - Local pdb debugging: Insert breakpoint() for an interactive REPL, launch scripts under python -m pdb without source edits, or debug pytest failures with --pdb (with xdist disabled). - Post-mortem inspection: Catch exceptions and inspect locals at the crash frame using pdb.post_mortem, excepthooks, or python -m pdb -c continue. - Remote debugging: Attach to already-running processes with debugpy's DAP protocol, PID injection, or the simpler remote-pdb over netcat for terminal-based workflows. - Use Case: A gateway subprocess misbehaves in production-like conditions. Add remote_pdb.set_trace() in the suspect handler, trigger the failing request, connect with nc 127.0.0.1 4444, and inspect the live call stack and variables. ## Quick Start Add a breakpoint() call at the suspect line in my Python file and walk me through inspecting the variables when execution pauses there.

Frequently Asked Questions about python-debugpy

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug Python code with pdb breakpoints?

Insert breakpoint() at the line you want to inspect and run the script normally; execution pauses there with a (Pdb) prompt. Use commands like n to step, p to print expressions, w for the stack trace, and interact for a full Python REPL in the current scope.

How to attach a debugger to a running Python process?

Use debugpy with python -m debugpy --listen 127.0.0.1:5678 --pid <pid> to inject into a running process, then connect a DAP client. Alternatively, add remote_pdb.set_trace() in the code and connect via nc 127.0.0.1 4444 for a plain pdb prompt.

debugpy vs remote-pdb for remote debugging?

debugpy speaks the DAP protocol and integrates with IDEs like VS Code, supporting threads and breakpoints set from the client. remote-pdb gives a plain pdb prompt over a TCP socket, which is simpler for terminal-only workflows when IDE integration is not needed.

Why does pdb not work with pytest-xdist?

pdb does not function under pytest-xdist because tests run in worker processes without an interactive terminal, so the prompt never appears and the test hangs. Disable xdist with -p no:xdist or -n 0 when using --pdb.

Why is my breakpoint() call not hitting?

Check whether PYTHONBREAKPOINT=0 is set, which disables all breakpoint() calls. Other common causes are running under pytest-xdist, or execution finishing before a remote debug client attached when wait_for_client() was omitted.

Can pdb debug multithreaded or asyncio Python code?

pdb only debugs the current thread and does not follow forks, so each thread or child process needs its own trace hook. For multithreaded code use debugpy, which is thread-aware; for asyncio, await works natively in pdb only on Python 3.13+.