{"id":628,"library":"debugpy","title":"Debugpy","description":"debugpy is an implementation of the Debug Adapter Protocol (DAP) for Python, enabling powerful debugging capabilities for various Python applications, including scripts, web apps, and remote processes. It is primarily used to connect Integrated Development Environments (IDEs) like VS Code to a running Python process for features such as setting breakpoints, stepping through code, and inspecting variables. The library is actively maintained, with frequent updates to support new Python versions and fix issues. The current version is 1.8.20.","status":"active","version":"1.8.20","language":"python","source_language":"en","source_url":"https://github.com/microsoft/debugpy","tags":["debugging","remote debugging","IDE integration","DAP","VS Code"],"install":[{"cmd":"pip install debugpy","lang":"bash","label":"Install debugpy"}],"dependencies":[{"reason":"debugpy requires Python 3.8 or newer to function correctly.","package":"python","optional":false}],"imports":[{"note":"debugpy superseded ptvsd as the default Python debugger in Visual Studio 2019 version 16.5 and later.","wrong":"import ptvsd","symbol":"debugpy","correct":"import debugpy"},{"note":"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.","symbol":"debugpy.listen","correct":"debugpy.listen((\"0.0.0.0\", 5678))"},{"note":"Blocks program execution until a debug client successfully attaches. Essential for debugging code from its very first line.","symbol":"debugpy.wait_for_client","correct":"debugpy.wait_for_client()"}],"quickstart":{"code":"import debugpy\nimport os\n\n# Configuration from environment variables for flexibility\nDEBUG_HOST = os.environ.get('DEBUG_HOST', '127.0.0.1')\nDEBUG_PORT = int(os.environ.get('DEBUG_PORT', '5678'))\nWAIT_FOR_DEBUGGER = os.environ.get('WAIT_FOR_DEBUGGER', 'true').lower() == 'true'\n\nprint(f\"[*] Debug server attempting to listen on {DEBUG_HOST}:{DEBUG_PORT}\")\n\ntry:\n    debugpy.listen((DEBUG_HOST, DEBUG_PORT))\n    print(f\"[*] Debug server listening. Host: {DEBUG_HOST}, Port: {DEBUG_PORT}\")\n    if WAIT_FOR_DEBUGGER:\n        print(\"[*] Waiting for debugger client to attach...\")\n        debugpy.wait_for_client()\n        print(\"[*] Debugger attached. Continuing program execution.\")\n    else:\n        print(\"[*] Not waiting for client. Program will continue.\")\n\n    # Your application logic starts here\n    name = \"World\"\n    message = f\"Hello, {name}! This is debugpy in action.\"\n    print(message)\n    # Example: A programmatic breakpoint\n    debugpy.breakpoint()\n    result = 10 * 2\n    print(f\"Calculated result: {result}\")\n\nexcept Exception as e:\n    print(f\"[ERROR] Failed to start debug server or an error occurred: {e}\")\n    import sys\n    sys.exit(1)\n","lang":"python","description":"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."},"warnings":[{"fix":"Update your `.vscode/launch.json` file to use `\"type\": \"debugpy\"` instead of `\"type\": \"python\"` for all Python debug configurations.","message":"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.","severity":"breaking","affected_versions":"Python Debugger extension (VS Code) versions from February 2024 onwards."},{"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()`.","message":"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`.","severity":"breaking","affected_versions":"Visual Studio 2019 version 16.5 and later, corresponding Python extensions for VS Code."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of debugpy."},{"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.","message":"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()`.","severity":"gotcha","affected_versions":"All versions of debugpy."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of debugpy, with improvements in recent 1.8.15+."},{"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.","message":"When debugging remotely, incorrect `pathMappings` in your IDE's launch configuration can prevent breakpoints from being hit or source code from being correctly correlated.","severity":"gotcha","affected_versions":"All versions of debugpy when used with an IDE for remote debugging."},{"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.","message":"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.","severity":"gotcha","affected_versions":"Specific Python versions (e.g., 3.14 had issues until recent fixes, Python 3.6/3.7 for older VS Code extensions)."}],"env_vars":null,"last_verified":"2026-05-12T16:56:24.799Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install 'debugpy' using pip: 'pip install debugpy'.","cause":"The 'debugpy' module is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'debugpy'"},{"fix":"Upgrade to Python 3.8 or later, or avoid using 'Literal' in your code.","cause":"The 'Literal' type is not available in Python versions prior to 3.8.","error":"ImportError: cannot import name 'Literal' from 'typing'"},{"fix":"Upgrade to Python 3.5 or later, or refactor code to avoid using 'module_from_spec'.","cause":"The 'module_from_spec' function is not available in Python versions prior to 3.5.","error":"ImportError: cannot import name 'module_from_spec' from 'importlib.util'"},{"fix":"Check for circular imports and ensure module paths are correctly set.","cause":"Circular imports or incorrect module paths can lead to this error.","error":"AttributeError: 'module' object has no attribute 'model'"},{"fix":"Verify that 'Node' is correctly defined and accessible in the module.","cause":"The 'Node' class or function is not defined or not accessible in the module.","error":"ImportError: cannot import name 'Node'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.8.20","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"49.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"49.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.2,"import_time_s":0.02,"mem_mb":1.7,"disk_size":"37M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.7,"disk_size":"37M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2,"disk_size":"52.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2,"disk_size":"52.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.05,"mem_mb":2,"disk_size":"41M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2,"disk_size":"41M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"44.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"44.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"35M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"35M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.2,"disk_size":"43.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.2,"disk_size":"43.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.2,"import_time_s":0.05,"mem_mb":2,"disk_size":"35M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2,"disk_size":"34M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"48.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"48.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.7,"import_time_s":0.02,"mem_mb":1.6,"disk_size":"36M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.6,"disk_size":"36M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":-1},{"runtime":"python:3.10-slim","exit_code":-1},{"runtime":"python:3.11-alpine","exit_code":-1},{"runtime":"python:3.11-slim","exit_code":-1},{"runtime":"python:3.12-alpine","exit_code":-1},{"runtime":"python:3.12-slim","exit_code":-1},{"runtime":"python:3.13-alpine","exit_code":-1},{"runtime":"python:3.13-slim","exit_code":-1},{"runtime":"python:3.9-alpine","exit_code":-1},{"runtime":"python:3.9-slim","exit_code":-1}]}}