Repository files navigation

An implementation of theDebug Adapter Protocol for Python 3.

OS	Coverage
Windows
Linux
Mac

For full details, see theCommand Line Reference.

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

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

-m debugpy --listen localhost:5678 --wait-for-client myfile.py

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

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

-m debugpy --listen 0.0.0.0:5678 myfile.py

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 becomessys.argv of the running process.

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.

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

The following command will ignore subprocesses started by the debugged process.

-m debugpy --listen localhost:5678 --pid 12345 --configure-subProcess False

For full details, see theAPI reference.

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

importdebugpydebugpy.listen(("localhost",5678))...

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

debugpy.listen(5678)...

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

importdebugpydebugpy.listen(5678)debugpy.wait_for_client()# blocks execution until client is attached...

Where available, debugpy supports the standardbreakpoint() function for programmatic breakpoints. Usedebugpy.breakpoint() function to get the same behavior whenbreakpoint() handler installed by debugpy is overridden by another handler. 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.

importdebugpydebugpy.listen(...)whileTrue:    ...breakpoint()# or debugpy.breakpoint()    ...

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 withdebugpy.log_to():

debugpy.log_to('path/to/logs')debugpy.listen(...)

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

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