Skip to content
An implementation of the Debug Adapter Protocol for Python
Python C++ Shell PowerShell HTML C
Branch: master
Clone or download


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add CODEOWNERS. Jul 23, 2019
.vscode Fix microsoft/ptvsd#2108: Mar 18, 2020
azure-pipelines Increase timeout for CI code coverage on Windows. Mar 7, 2020
coverage Add code coverage for tests (excluding ptvsd.server and pydevd). Sep 19, 2019
doc Rename ptvsd -> debugpy. Jan 17, 2020
packaging Rename ptvsd -> debugpy. Jan 17, 2020
src/debugpy Show bytecode when source code cannot be fetched. Mar 29, 2020
tests Fix microsoft/ptvsd#2108: Mar 18, 2020
.coveragerc Fix coverage Jan 31, 2020
.env Enable discovery of ptvsd tests in VSCode. Feb 26, 2019
.flake8 Rename ptvsd -> debugpy. Jan 17, 2020
.gitattributes Rename ptvsd -> debugpy. Jan 17, 2020
.gitignore Add code coverage for tests (excluding ptvsd.server and pydevd). Sep 19, 2019 Rename ptvsd -> debugpy. Jan 17, 2020
.travis.yml Don't run codecov Tox environments on Travis. Dec 16, 2019 Rename ptvsd -> debugpy. Jan 17, 2020 Rename ptvsd -> debugpy. Jan 17, 2020 Rename ptvsd -> debugpy. Jan 17, 2020
LICENSE Rename ptvsd -> debugpy. Jan 17, 2020 Rename ptvsd -> debugpy. Jan 17, 2020 Refactor debugpy API and CLI for clarity and consistency. Feb 11, 2020 Rename ptvsd -> debugpy. Jan 17, 2020 Rename ptvsd -> debugpy. Jan 17, 2020
clean.cmd Refactor tests.debug to accommodate ptvsd.server spawning the adapter… Sep 26, 2019
debugpy.code-workspace Rename ptvsd -> debugpy. Jan 17, 2020
pyproject.toml Rename ptvsd -> debugpy. Jan 17, 2020
pytest.ini Adjust test timeout for CI. Nov 19, 2019
setup.cfg Rename ptvsd -> debugpy. Jan 17, 2020 Fix #14: Update package metadata in Feb 1, 2020 Exclude server directory from sonar Feb 5, 2020
tox.ini Actually run full test matrix for DEBUGBY_TESTS_FULL=1. Mar 5, 2020 Disable 'dirty' flag for version numbers. Apr 19, 2018

debugpy - a debugger for Python

Build Status GitHub PyPI PyPI


OS Coverage
Windows Azure DevOps coverage
Linux Azure DevOps coverage
Mac Azure DevOps coverage

This debugger implements the Debug Adapter Protocol: debugProtocol.json

debugpy CLI Usage

Debugging a script file

To run a script file with debugging enabled, but without waiting for the client to attach (i.e. code starts executing immediately):

-m debugpy --listen localhost:5678

To wait until the client attaches before running your code, use the --wait-for-client switch.

-m debugpy --listen localhost:5678 --wait-for-client

The hostname passed to --listen specifies the interface on which the debug adapter will be listening for connections from DAP clients. It can be omitted, with only the port number specified:

-m debugpy --listen 5678 ...

in which case the default interface is

To be able to attach from another machine, make sure that the adapter is listening on a public interface - using will make it listen on all available interfaces:

-m debugpy --listen

This should only be done on secure networks, since anyone who can connect to the specified port can then execute arbitrary code within the debugged process.

To pass arguments to the script, just specify them after the filename. This works the same as with Python itself - everything up to the filename is processed by debugpy, but everything after that becomes sys.argv of the running process.

Debugging a module

To run a module, use the -m switch instead of filename:

-m debugpy --listen localhost:5678 -m mymodule

Same as with scripts, command line arguments can be passed to the module by specifying them after the module name. All other debugpy switches work identically in this mode; in particular, --wait-for-client can be used to block execution until the client attaches.

Attaching to a running process by ID

The following command injects the debugger into a process with a given PID that is running Python code. Once the command returns, a debugpy server is running within the process, as if that process was launched via -m debugpy itself.

-m debugpy --listen localhost:5678 --pid 12345

debugpy Import usage

Enabling debugging

At the beginning of your script, import debugpy, and call debugpy.listen() to start the debug adapter, passing a (host, port) tuple as the first argument.

import debugpy
debugpy.listen(("localhost", 5678))

As with the --listen command line switch, hostname can be omitted, and defaults to "":


Waiting for the client to attach

Use the debugpy.wait_for_client() function to block program execution until the client is attached.

import debugpy
debugpy.wait_for_client()  # blocks execution until client is attached

breakpoint() function

In Python 3.7 and above, debugpy supports the standard breakpoint() function. Use debugpy.breakpoint() function for similar behavior and compatibility with older versions of Python. If the debugger is attached when either of these functions is invoked, it will pause execution on the calling line, as if it had a breakpoint set. If there's no client attached, the functions do nothing, and the code continues to execute normally.

import debugpy

while True:
    breakpoint()  # or debugpy.breakpoint() on 3.6 and below

Debugger logging

To enable debugger internal logging via CLI, the --log-to switch can be used:

-m debugpy --log-to path/to/logs ...

When using the API, the same can be done with debugpy.log_to():


In both cases, the environment variable DEBUGPY_LOG_DIR can also be set to the same effect.

When logging is enabled, debugpy will create several log files with names matching debugpy*.log in the specified directory, corresponding to different components of the debugger. When subprocess debugging is enabled, separate logs are created for every subprocess.

You can’t perform that action at this time.