{"id":7522,"library":"ptvsd","title":"ptvsd (Python Tools for Visual Studio Debugger)","description":"ptvsd is a remote debugging server for Python, primarily used to enable debugging capabilities in development environments like Visual Studio and Visual Studio Code. While its last stable release was 4.3.2 in August 2019, it has largely been superseded by `debugpy`, which is based on ptvsd's development branch. All future development for Microsoft's Python debugger is happening in `debugpy`.","status":"deprecated","version":"4.3.2","language":"en","source_language":"en","source_url":"https://github.com/microsoft/ptvsd","tags":["debugging","remote debugging","visual studio","visual studio code","microsoft","deprecated","debugpy"],"install":[{"cmd":"pip install ptvsd","lang":"bash","label":"Install ptvsd"}],"dependencies":[],"imports":[{"note":"While specific functions can be imported, the common and recommended practice is to import the module as a whole (import ptvsd) and then call methods like ptvsd.enable_attach().","wrong":"from ptvsd import enable_attach","symbol":"ptvsd","correct":"import ptvsd"}],"quickstart":{"code":"import ptvsd\nimport os\n\n# Enable remote debugging. By default, listens on all interfaces (0.0.0.0) and port 5678.\n# The 'address' can be configured via environment variables for flexibility.\n# For a more secure setup, specify a host (e.g., '127.0.0.1') and/or a secret (ptvsd 3.x required it).\n\n# Example using environment variables for host and port\nDEBUG_HOST = os.environ.get('PTVSD_HOST', '0.0.0.0')\nDEBUG_PORT = int(os.environ.get('PTVSD_PORT', 5678))\n\nprint(f\"Waiting for debugger attach on {DEBUG_HOST}:{DEBUG_PORT}\")\nptvsd.enable_attach(address=(DEBUG_HOST, DEBUG_PORT))\n\n# Optional: Wait for the debugger to attach before continuing execution.\n# This is useful when debugging script startup.\n# Remove or comment out in production or if your debugger automatically attaches early.\nptvsd.wait_for_attach()\n\nprint(\"Debugger attached. Continuing execution...\")\n\ndef my_function():\n    x = 10\n    y = 20\n    # Use breakpoint() for Python 3.7+ or ptvsd.break_into_debugger() for older Python versions\n    breakpoint() # This will pause execution if a debugger is attached\n    z = x + y\n    print(f\"Result: {z}\")\n\nmy_function()\n","lang":"python","description":"This quickstart demonstrates how to initialize ptvsd for remote debugging within a Python script. It sets up a listening server that a debugger (e.g., Visual Studio Code) can connect to. It uses environment variables for configuration for better portability and includes an optional `wait_for_attach()` call to pause execution until the debugger connects. A `breakpoint()` call is included to show how to trigger a debugger pause during execution."},"warnings":[{"fix":"Migrate your debugger configuration and code to use `debugpy`. For Visual Studio Code and Visual Studio 2019 (v16.5+), the transition to `debugpy` should be automatic with up-to-date extensions. For manual usage, replace `import ptvsd` with `import debugpy` and adjust API calls accordingly (e.g., `debugpy.listen` instead of `ptvsd.enable_attach`).","message":"ptvsd is officially deprecated. All future development and support for Microsoft's Python debugger is happening in `debugpy`. Users are strongly encouraged to migrate to `debugpy` for continued support, bug fixes, and new features.","severity":"breaking","affected_versions":"All versions, as of ptvsd 5.x development branch transition to debugpy."},{"fix":"Upgrade Visual Studio to version 2019 (v16.5+) or later to automatically use `debugpy`. If using an older VS version, ensure `ptvsd` in your Python environment matches the version expected by your Visual Studio installation, or enable the 'legacy debugger' option in Visual Studio's Python debugging settings.","message":"Older versions of Visual Studio (e.g., VS 2019 v16.4 and earlier, VS 2017) might bundle specific, sometimes outdated, versions of ptvsd, leading to version conflicts or debugger instability if a different version is installed in your Python environment.","severity":"gotcha","affected_versions":"Visual Studio 2017, Visual Studio 2019 (v16.0-16.4)"},{"fix":"Add `import multiprocessing; multiprocessing.set_start_method('spawn', True)` at the very beginning of your main script, before any other multiprocessing-related code. This ensures consistent behavior across platforms.","message":"Multiprocess debugging on Linux/macOS with ptvsd can lead to issues unless the 'spawn' start method is explicitly set for the `multiprocessing` module.","severity":"gotcha","affected_versions":"All ptvsd 4.x versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `ptvsd` is installed in your target Python environment using `pip install ptvsd`. Verify that your IDE (e.g., VS Code) is configured to use the correct Python interpreter where `ptvsd` is installed.","cause":"`ptvsd` is not installed in the active Python environment or the wrong Python interpreter is being used by the IDE/debugger.","error":"ModuleNotFoundError: No module named 'ptvsd'"},{"fix":"1. **Check versions:** Ensure `ptvsd` (or preferably `debugpy`) is up-to-date and compatible with your IDE. 2. **Verify host/port:** Double-check that the `address` parameter in `ptvsd.enable_attach()` matches the host and port specified in your debugger's attach configuration. 3. **Firewall:** Confirm that no firewall is blocking the specified port on either the client or server side. 4. **Path Mappings:** In your `launch.json` or equivalent debugger configuration, ensure `localRoot` and `remoteRoot` correctly map your local project paths to the remote execution paths. Also, check `justMyCode` setting.","cause":"This can be caused by several factors: ptvsd version mismatch with the debugger client, incorrect host/port configuration, firewall blocking the connection, or incorrect path mappings in the debugger's launch configuration (e.g., `launch.json`).","error":"Debugger not attaching / breakpoints not being hit / 'Cannot start experimental Python debugger'"},{"fix":"Ensure you are using the latest stable `ptvsd` (4.3.2) or, preferably, migrate to `debugpy`. If the issue persists, try isolating the environment to see if other packages cause conflicts. Check the GitHub issues for `ptvsd` or `debugpy` for specific version-related workarounds.","cause":"This error can sometimes arise from compatibility issues with specific Python versions or other installed libraries, particularly when older versions of `ptvsd` are used.","error":"'module' object has no attribute 'timeout' (or similar AttributeError related to ptvsd internal modules)"}]}