python-debugpy

Debug Python failures with pdb breakpoints and remote debugpy attach sessions.

Updated May 4, 2026
One-click install
npx skills add https://github.com/JamesFincher/gengar --skill python-debugpy-jamesfincher
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: python-debugpy
Source: https://github.com/JamesFincher/gengar/tree/main/skills/software-development/python-debugpy
Command: npx skills add https://github.com/JamesFincher/gengar --skill python-debugpy-jamesfincher

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you diagnose failing Python behavior by providing interactive local debugging with pdb and remote/attach debugging with debugpy when you cannot simply restart the process.

Core Features & Use Cases

  • Local interactive debugging with pdb: Drop into a REPL at a breakpoint() or start a script under python -m pdb to inspect state where the bug happens.
  • Remote/attach debugging with debugpy (DAP): Attach to long-lived processes such as a gateway or subprocess to inspect locals without stopping the whole system.
  • Pytest-focused debugging patterns: Use the project’s test runner with --pdb or --trace for failures, while avoiding known incompatibilities with xdist.
  • Post-mortem inspection: Inspect locals at the exception site using pdb.post_mortem to understand what changed right before the crash.
  • Use Case: A test fails because a value is missing in a complex data transformation; add breakpoint() at the suspect line, reproduce, then use p/pp/where to see how the program arrived there.

Quick Start

Tell the agent to help you debug a failing test by running the specific test with pdb while disabling xdist.

Frequently Asked Questions about python-debugpy

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

FAQPage Schema
How do I debug a failing pytest test with pdb without breaking parallel execution?

To debug a failing pytest test, run the specific test with the `--pdb` or `--trace` flag while disabling xdist. This drops you into an interactive pdb REPL at the failure point to inspect local state safely.

How does remote debugging with debugpy work for long-running Python processes?

Remote debugging with debugpy uses the Debug Adapter Protocol (DAP) to attach to a running Python process, such as a gateway or subprocess. This allows you to inspect local variables and execution frames without stopping or restarting the system.

Can I inspect local variables at the exact site of an unhandled Python exception?

Yes, you can perform post-mortem inspection using `pdb.post_mortem` to analyze an unhandled Python exception. This opens an interactive REPL at the exact crash site to inspect local variables and understand what changed right before the failure.

What is the best way to diagnose a Python data transformation issue when a value is missing?

The best way to diagnose a missing value in a Python data transformation is to insert a `breakpoint()` at the suspect line, reproduce the issue, and use pdb commands like `p`, `pp`, and `where` to trace how the program arrived at that state.

Does interactive pdb debugging work with pytest-xdist parallel test runners?

Interactive pdb debugging has known incompatibilities with pytest-xdist. To use pdb breakpoints or the `--pdb` flag correctly, you must disable xdist parallel execution to ensure safe handling and proper frame inspection.

When should I use debugpy attach instead of running a Python script under pdb?

Use debugpy attach instead of pdb when you cannot restart the process, such as when debugging long-lived gateway or subprocess execution. Debugpy lets you attach to the running process to inspect state, whereas pdb requires starting the script under its module.