ptvsd (Python Tools for Visual Studio Debugger)

Common errors

• ModuleNotFoundError: No module named 'ptvsd'

  cause `ptvsd` is not installed in the active Python environment or the wrong Python interpreter is being used by the IDE/debugger.
  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.

• Debugger not attaching / breakpoints not being hit / 'Cannot start experimental Python debugger'

  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`).
  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.

• 'module' object has no attribute 'timeout' (or similar AttributeError related to ptvsd internal modules)

  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.
  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.

Warnings

• breaking 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.
  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`).
• gotcha 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.
  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.
• gotcha Multiprocess debugging on Linux/macOS with ptvsd can lead to issues unless the 'spawn' start method is explicitly set for the `multiprocessing` module.
  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.

Install

• pip install ptvsd Install ptvsd

Imports

• ptvsd
  wrong:

  from ptvsd import enable_attach

  correct:

  import ptvsd

  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().

Quickstart

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.

import ptvsd
import os

# Enable remote debugging. By default, listens on all interfaces (0.0.0.0) and port 5678.
# The 'address' can be configured via environment variables for flexibility.
# For a more secure setup, specify a host (e.g., '127.0.0.1') and/or a secret (ptvsd 3.x required it).

# Example using environment variables for host and port
DEBUG_HOST = os.environ.get('PTVSD_HOST', '0.0.0.0')
DEBUG_PORT = int(os.environ.get('PTVSD_PORT', 5678))

print(f"Waiting for debugger attach on {DEBUG_HOST}:{DEBUG_PORT}")
ptvsd.enable_attach(address=(DEBUG_HOST, DEBUG_PORT))

# Optional: Wait for the debugger to attach before continuing execution.
# This is useful when debugging script startup.
# Remove or comment out in production or if your debugger automatically attaches early.
ptvsd.wait_for_attach()

print("Debugger attached. Continuing execution...")

def my_function():
    x = 10
    y = 20
    # Use breakpoint() for Python 3.7+ or ptvsd.break_into_debugger() for older Python versions
    breakpoint() # This will pause execution if a debugger is attached
    z = x + y
    print(f"Result: {z}")

my_function()