debugpy: An Advanced Debugger for Python Development

Introduction

debugpy is a comprehensive debugger for Python 3, developed by Microsoft. It implements the Debug Adapter Protocol (DAP), enabling seamless integration with various IDEs and editors that support DAP, such as Visual Studio Code. debugpy is designed to provide a rich debugging experience, allowing you to step through code, inspect variables, set breakpoints, and much more, whether you are debugging local scripts, modules, or attaching to running processes.

Installation

debugpy can be easily installed using pip, the Python package installer.

pip install debugpy

Examples

CLI Usage

debugpy offers a flexible command-line interface for debugging.

Debugging a script file:
To run a script with debugging enabled, listening on localhost:5678:

python -m debugpy --listen localhost:5678 myfile.py

To wait for a client to attach before execution:

python -m debugpy --listen localhost:5678 --wait-for-client myfile.py

Debugging a module:
You can debug a Python module using the -m switch:

python -m debugpy --listen localhost:5678 -m mymodule

Attaching to a running process:
Inject the debugger into an already running Python process by its PID:

python -m debugpy --listen localhost:5678 --pid 12345

API Usage

For more programmatic control, debugpy provides a Python API.

Enabling debugging:
Import debugpy and call debugpy.listen() at the beginning of your script:

import debugpy
debugpy.listen(("localhost", 5678))
# Your application code

Waiting for the client:
To pause execution until a debugger client connects:

import debugpy
debugpy.listen(5678)
debugpy.wait_for_client()  # Blocks execution until client is attached
# Your application code

Programmatic breakpoints:
Use breakpoint() or debugpy.breakpoint() to set a breakpoint programmatically. Execution will pause if a client is attached.

import debugpy
debugpy.listen(...)

while True:
    # ...
    breakpoint()  # or debugpy.breakpoint()
    # ...

Why Use debugpy?

debugpy stands out as a powerful debugging tool for several reasons:

• DAP Compliance: Its adherence to the Debug Adapter Protocol ensures broad compatibility with modern development environments.
• Flexibility: It supports both command-line and API-driven debugging, catering to different integration needs and workflows.
• Comprehensive Features: From basic step-through debugging to attaching to running processes and handling subprocesses, debugpy covers a wide range of debugging scenarios.
• Microsoft Backing: Developed by Microsoft, it benefits from continuous development and integration, especially within tools like Visual Studio Code.

Links

• GitHub Repository: https://github.com/microsoft/debugpy
• Command Line Reference: https://github.com/microsoft/debugpy/wiki/Command-Line-Reference
• API Reference: https://github.com/microsoft/debugpy/wiki/API-Reference
• PyPI: https://pypi.org/project/debugpy/