Command Line Reference

Overview

This is the recommended way to use the debugger. One advantage of using the CLI is that you don't have to change your scripts to have debugger imports.

Usage Reference

Command Line

python -m debugpy --listen [<address>:]<port>
    [--wait-for-client]
    [--configure-<name> <value>]...
    [--log-to <path>] [--log-to-stderr]
    <filename> | -m <module> | -c <code> | --pid <pid>
    [<arg>]...

Quick and Easy

Recipe	Command line
Running a script	python -m debugpy --listen 5678 --wait-for-client ./myscript.py
Running a module	python -m debugpy --listen 5678 --wait-for-client -m mymodule
Running code string	python -m debugpy --listen 5678 --wait-for-client -c "import sys;print(sys.argv)"

--listen [<address>:]<port>

Required. Use this argument to specify the host address and port for the debug adapter server. This is the address that you will use in your debug configuration. Default host address is 127.0.0.1.

Example 1:

Here we start the debugger using port 5678. The assumption here is that myscript.py is a long running script. The command below loads the debugger and starts the script. It will not block user code from running. See details for --wait-for-client for more details on blocking user code.

python -m debugpy --listen 5678 ./myscript.py

To connect to the debugger from VS Code, you can use this configuration:

{
    "name": "Attach",
    "type": "python",
    "request": "attach",
    "host": "localhost",
    "port": 5678,
}

Example 2: Working with remote code or code running in docker container

Here we start the debugger using host 0.0.0.0 (see remarks below) and port 5678. The assumption here is that myscript.py is a long running script. The command below loads the debugger and starts the script. It will not block user code from running. See details for --wait-for-client for more details on blocking user code.

You would run this command on your remote machine or in the container. Be sure to all access to port 5676 when using remote, or map internal port to host ports if using docker container (like docker run -p 5678:5678).

python -m debugpy --listen 0.0.0.0:5678 ./myscript.py

To connect to the debugger from VS Code, you can use this configuration:

{
    "name": "Attach",
    "type": "python",
    "request": "attach",
    "host": "remote-machine-name", // replace this with remote machine name
    "port": 5678,
}

REMARKS: When using host value other than 127.0.0.1 or localhost, you will be opening a port to allow access from any machine. We recommend using SSH tunnels when working with remote. See how to use SSH with debugpy for more details.

--wait-for-client

Optional. Use this CLI switch to block your code from running till you connect to the debug server. This is useful if you want to debug from the first line of your code.

Usage

python -m debugpy --listen 5678 --wait-for-client ./myscript.py

--log-to <path>

Optional. Use this switch to provide a path to an existing directory where logs will be saved.

--log-to-stderr

Optional. Use this switch to allow debugpy to write logs directly to stderr.

--pid <pid>

Use this to attach the debugger to a process that is already running. This is useful to attach the debugger to embedded python (think Maya running python script).

--configure-<name> <value>

TBD