Skip to main content

debugpy

debugpy is the official Python debugger from Microsoft, designed to bring powerful, modern debugging to Visual Studio Code, PyCharm, Jupyter, and any editor supporting the Debug Adapter Protocol (DAP). It enables developers to set breakpoints, inspect variables, step through code, and debug complex applications with ease—all from within their favorite editor. Whether you're working locally or need to debug code running on a remote server, debugpy provides a seamless, visual debugging experience that accelerates troubleshooting and development.

Basics​

Installation​

VS Code (Automatic)​

debugpy is automatically installed with the Python extension for VS Code:

  1. Install the Python extension from the marketplace
  2. Open a Python file
  3. debugpy is ready to use

Manual Installation​

# Install debugpy
pip install debugpy

# Or with conda
conda install debugpy

Verify Installation​

import debugpy
print(debugpy.__version__)

Setting Breakpoints​

In VS Code or compatible editors:

  1. Click in the gutter next to line numbers to set breakpoints
  2. Red dots indicate active breakpoints
  3. Right-click breakpoints for advanced options

Programmatic Breakpoints​

import debugpy

# Set a breakpoint programmatically
debugpy.breakpoint()  # Execution will pause here

# Alternative: use built-in breakpoint()
breakpoint()  # Python 3.7+ - uses debugpy in VS Code

Remote Debugging​

Debug Python applications running on remote servers, containers, or different machines using debugpy's remote debugging capabilities.

Server Setup (Remote Application)​

# remote_app.py
import debugpy

# Listen for debugger connections
debugpy.listen(("0.0.0.0", 5678))
print("Waiting for debugger to attach...")
debugpy.wait_for_client()
print("Debugger attached!")

# Your application code
def main():
    data = [1, 2, 3, 4, 5]
    result = sum(data)
    print(f"Result: {result}")

if __name__ == "__main__":
    main()

Client Setup (Local VS Code)​

Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Remote Attach",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "remote-server-ip",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "/path/to/remote/code"
                }
            ]
        }
    ]
}

IDE Integration​

Deep integration of debugpy with popular development environments and frameworks for enhanced debugging workflows.

Visual Studio Code Integration​

Python Extension Setup​

debugpy comes pre-installed with the Python extension:

  1. Install the Python extension from the marketplace
  2. Open a Python file or folder
  3. Create or modify .vscode/launch.json for custom configurations

Launch Configurations​

Basic File Debugging​
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}"
        }
    ]
}
Module Debugging​
{
    "name": "Python: Module",
    "type": "python",
    "request": "launch",
    "module": "mypackage.main",
    "console": "integratedTerminal"
}
Script with Arguments​
{
    "name": "Python: Script with Arguments",
    "type": "python",
    "request": "launch",
    "program": "${file}",
    "args": ["--arg1", "value1"],
    "console": "integratedTerminal"
}

Advanced Features​

Master advanced debugging techniques and configurations for complex applications and scenarios.

Multi-Process Debugging​

Parent-Child Process Debugging​

import debugpy
import multiprocessing as mp
import os

def setup_multiprocess_debugging():
    """Configure debugging for multi-process applications"""
    # Main process debugger
    debugpy.listen(("0.0.0.0", 5678))
    
    # Configure subprocess debugging
    debugpy.configure(subProcess=True)
    print("Multi-process debugging enabled")

def worker_process(worker_id, debug_port_base=5680):
    """Worker process with individual debug port"""
    worker_port = debug_port_base + worker_id
    
    try:
        debugpy.listen(("0.0.0.0", worker_port))
        print(f"Worker {worker_id} debugger on port {worker_port}")
    except RuntimeError:
        print(f"Worker {worker_id}: Debug port {worker_port} already in use")
    
    # Worker logic with debugging capability
    breakpoint()  # Can debug each worker independently
    
    data = [i * worker_id for i in range(5)]
    result = sum(data)
    print(f"Worker {worker_id} result: {result}")
    return result

def main():
    setup_multiprocess_debugging()
    
    # Create worker processes
    processes = []
    for i in range(3):
        p = mp.Process(target=worker_process, args=(i,))
        processes.append(p)
        p.start()

    for p in processes:
        p.join()

if __name__ == "__main__":
    main()

Conditional Breakpoints​

Set breakpoints that only trigger under specific conditions:

# Example: Break only when x > 10
breakpoint() if x > 10 else None

Logpoints​

Logpoints allow you to log messages without pausing execution:

{
    "name": "Python: Logpoint",
    "type": "python",
    "request": "launch",
    "program": "${file}",
    "logMessage": "Variable x = {x}"
}

Summary​

debugpy is a versatile and powerful debugger for Python, offering features for local, remote, and advanced debugging scenarios. Its integration with modern IDEs and support for complex debugging workflows make it an essential tool for Python developers.