Debugpy

Warnings

• breaking When using VS Code, the `type` field in `launch.json` debug configurations for Python debugging has changed from `"python"` to `"debugpy"`. Older configurations using `"python"` will no longer work with recent versions of the Python Debugger extension.
  Fix: Update your `.vscode/launch.json` file to use `"type": "debugpy"` instead of `"type": "python"` for all Python debug configurations.
• breaking debugpy replaced ptvsd as the default remote debugging library in Visual Studio and the Python extension for VS Code. Projects or tutorials referencing `ptvsd` APIs will need to be updated to use `debugpy`.
  Fix: Migrate any `ptvsd` specific code or configurations to use `debugpy` equivalents. For example, replace `ptvsd.enable_attach()` with `debugpy.listen()` or `debugpy.wait_for_client()`.
• gotcha Exposing the debug server to all network interfaces by calling `debugpy.listen(('0.0.0.0', port))` can pose a security risk. Anyone on the network who can connect to that port can execute arbitrary code within the debugged process.
  Fix: Only use `'0.0.0.0'` on secure, isolated networks or when specifically required for container/remote debugging setups where network access is controlled. For local debugging, explicitly use `'127.0.0.1'` or omit the host for the default.
• gotcha Code executed before `debugpy.listen()` (or before `python -m debugpy --listen...`) cannot be debugged. If you want to debug from the very beginning of your script, you must explicitly call `debugpy.wait_for_client()` immediately after `debugpy.listen()`.
  Fix: Include `debugpy.wait_for_client()` after `debugpy.listen()` to pause execution until your IDE's debugger attaches. This ensures breakpoints set at the start of your script are hit.
• gotcha Debugging child processes can be tricky. By default, `debugpy` might not automatically inject itself into subprocesses. Recent versions include fixes, but explicit configuration may still be needed.
  Fix: When launching via CLI, use `--configure-subProcess False` to explicitly ignore subprocesses if not needed, or investigate specific IDE configurations for subprocess debugging. Ensure `debugpy` version 1.8.15 or newer for improved child process handling.
• gotcha When debugging remotely, incorrect `pathMappings` in your IDE's launch configuration can prevent breakpoints from being hit or source code from being correctly correlated.
  Fix: Ensure that your IDE's launch configuration (e.g., `.vscode/launch.json`) accurately maps the local project root (`localRoot`) to the remote project root (`remoteRoot`). For example, `"localRoot": "${workspaceFolder}", "remoteRoot": "."` or the specific absolute paths on both sides.
• gotcha While debugpy itself supports Python 3.8+, issues have been reported with newer Python versions (e.g., 3.14) requiring specific debugpy fixes. Conversely, debugging older Python versions (e.g., 3.6, 3.7) with current VS Code Python extensions requires installing older, specific versions of the VS Code extensions.
  Fix: Always use a `debugpy` version compatible with your target Python interpreter. If debugging Python <3.8, you might need to use an older VS Code Python extension that bundled an earlier `debugpy` version. Check `debugpy` release notes for specific Python version compatibility and fixes.

Install

• pip install debugpy Install debugpy

Imports

• debugpy

  import debugpy

  debugpy superseded ptvsd as the default Python debugger in Visual Studio 2019 version 16.5 and later.
• debugpy.listen

  debugpy.listen(("0.0.0.0", 5678))

  Initializes the debug server to listen for an IDE client connection. The host defaults to '127.0.0.1' if not specified, which only allows local connections. For remote debugging, use '0.0.0.0' (for all interfaces) or a specific IP address.
• debugpy.wait_for_client

  debugpy.wait_for_client()

  Blocks program execution until a debug client successfully attaches. Essential for debugging code from its very first line.

Quickstart

This quickstart demonstrates how to integrate `debugpy` into a Python script to enable remote debugging. It sets up a debug server, optionally waits for a client to attach (controlled by `WAIT_FOR_DEBUGGER` environment variable), and includes a programmatic breakpoint. To run: 1. Save as `app.py`. 2. On the remote machine (or local for testing), run `python app.py`. For remote access, ensure `DEBUG_HOST` is set to '0.0.0.0'. 3. In your IDE (e.g., VS Code), configure a 'Python: Remote Attach' launch configuration targeting the specified host and port (default 127.0.0.1:5678). Then start the debugger in your IDE.

import debugpy
import os

# Configuration from environment variables for flexibility
DEBUG_HOST = os.environ.get('DEBUG_HOST', '127.0.0.1')
DEBUG_PORT = int(os.environ.get('DEBUG_PORT', '5678'))
WAIT_FOR_DEBUGGER = os.environ.get('WAIT_FOR_DEBUGGER', 'true').lower() == 'true'

print(f"[*] Debug server attempting to listen on {DEBUG_HOST}:{DEBUG_PORT}")

try:
    debugpy.listen((DEBUG_HOST, DEBUG_PORT))
    print(f"[*] Debug server listening. Host: {DEBUG_HOST}, Port: {DEBUG_PORT}")
    if WAIT_FOR_DEBUGGER:
        print("[*] Waiting for debugger client to attach...")
        debugpy.wait_for_client()
        print("[*] Debugger attached. Continuing program execution.")
    else:
        print("[*] Not waiting for client. Program will continue.")

    # Your application logic starts here
    name = "World"
    message = f"Hello, {name}! This is debugpy in action."
    print(message)
    # Example: A programmatic breakpoint
    debugpy.breakpoint()
    result = 10 * 2
    print(f"Calculated result: {result}")

except Exception as e:
    print(f"[ERROR] Failed to start debug server or an error occurred: {e}")
    import sys
    sys.exit(1)