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 | --connect
    [<host>:]<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

Tells the debug server to wait for an incoming connection from the client on the specified interface and port. The corresponding debug configuration should use "connect" with matching "host" and "port" entries.

--connect

Tells the debug server to connect to a client that is waiting for incoming connections at the specified address and port. The corresponding debug configuration should use "listen" with matching "host" and "port" entries.

[<host>:]<port>

Required. Use this argument to specify the interface and port to listen on, or host and port to connect to. The same values should be used in the debug configuration. Host can be either a hostname or an IP address; if not specified, it defaults to 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",
    "connect": {
        "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",
    "connect": {
        "host": "remote-machine-name", // replace this with remote machine name
        "port": 5678,
    }
}

WARNING: 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 debugger logs will be generated. Use when reporting debugpy issues.

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

Sets a debug property that must be known to the debug server before the client connects. Such properties can be used directly in "launch" configurations, because in that case the debuggee process after the configuration is passed. But for "attach" configurations, the process can run for a long time before it receives the debug configuration from an attaching client, and thus a different mechanism must be used to set the property values.

Currently, the only property like that is "subProcess". If you don't want the debug server to automatically inject itself into subprocesses spawned by the process you're attaching to, specify it like so:

python -m debugpy ... --configure-subProcess false ...

This is the "attach" equivalent to the following "launch" debug configuration:

{
    "subProcess": false
}