Install & Compatibility
Where this runs
tested against v1.8.21 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.048s · 48.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.042s · 36MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
debugpy
✓ import debugpy
✗ import ptvsd
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.
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)
Debug
Known issues
breakingWhen 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.fixUpdate your `.vscode/launch.json` file to use `"type": "debugpy"` instead of `"type": "python"` for all Python debug configurations.
affects: Python Debugger extension (VS Code) versions from February 2024 onwards.
breakingdebugpy 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`.fixMigrate any `ptvsd` specific code or configurations to use `debugpy` equivalents. For example, replace `ptvsd.enable_attach()` with `debugpy.listen()` or `debugpy.wait_for_client()`.
affects: Visual Studio 2019 version 16.5 and later, corresponding Python extensions for VS Code.
gotchaExposing 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.fixOnly 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.
affects: All versions of debugpy.
gotchaCode 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()`.fixInclude `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.
affects: All versions of debugpy.
gotchaDebugging 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.fixWhen 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.
affects: All versions of debugpy, with improvements in recent 1.8.15+.
gotchaWhen debugging remotely, incorrect `pathMappings` in your IDE's launch configuration can prevent breakpoints from being hit or source code from being correctly correlated.fixEnsure 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. affects: All versions of debugpy when used with an IDE for remote debugging.
gotchaWhile 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.fixAlways 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.
affects: Specific Python versions (e.g., 3.14 had issues until recent fixes, Python 3.6/3.7 for older VS Code extensions).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'debugpy'
The 'debugpy' module is not installed in the current Python environment.
fixInstall 'debugpy' using pip: 'pip install debugpy'.
ImportError: cannot import name 'Literal' from 'typing'
The 'Literal' type is not available in Python versions prior to 3.8.
fixUpgrade to Python 3.8 or later, or avoid using 'Literal' in your code.
ImportError: cannot import name 'module_from_spec' from 'importlib.util'
The 'module_from_spec' function is not available in Python versions prior to 3.5.
fixUpgrade to Python 3.5 or later, or refactor code to avoid using 'module_from_spec'.
AttributeError: 'module' object has no attribute 'model'
Circular imports or incorrect module paths can lead to this error.
fixCheck for circular imports and ensure module paths are correctly set.
ImportError: cannot import name 'Node'
The 'Node' class or function is not defined or not accessible in the module.
fixVerify that 'Node' is correctly defined and accessible in the module.
Upgrade
Version history
1.8.21latest on PyPI · released Jun 1, 2026
Audit
Dependencies
pythonrequireddebugpy requires Python 3.8 or newer to function correctly.