Debugpy

Common errors

Warnings

Install compatibility verified last tested: 2026-05-12

Imports

• debugpy
  wrong

  import ptvsd

  correct

  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 stale last tested: 2026-04-24

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)