@@ -16,7 +16,9 @@ The module :mod:`pdb` defines an interactive source code debugger for Python
1616programs. It supports setting (conditional) breakpoints and single stepping at
1717the source line level, inspection of stack frames, source code listing, and
1818evaluation of arbitrary Python code in the context of any stack frame. It also
19- supports post-mortem debugging and can be called under program control.
19+ supports post-mortem debugging and can be called under program control. The
20+ :mod: `pdb ` module also supports remote attaching to a running Python process
21+ using a ``-p PID `` command-line option.
2022
2123..index ::
2224 single: Pdb (class in pdb)
@@ -80,7 +82,10 @@ The debugger's prompt is ``(Pdb)``, which is the indicator that you are in debug
8082You can also invoke:mod: `pdb ` from the command line to debug other scripts. For
8183example::
8284
83- python -m pdb [-c command] (-m module | pyfile) [args ...]
85+ python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]
86+
87+ Remote debugging is supported by attaching to a running Python process using
88+ the ``-p `` option and a PID.
8489
8590When invoked as a module, pdb will automatically enter post-mortem debugging if
8691the program being debugged exits abnormally. After post-mortem debugging (or
@@ -104,6 +109,27 @@ useful than quitting the debugger upon program's exit.
104109 ..versionchanged ::3.7
105110 Added the ``-m `` option.
106111
112+ ..option ::-p ,--pid <pid >
113+
114+ Attach to the process with the specified PID.
115+
116+ ..versionchanged ::3.14
117+ Added the ``-p `` and ``--pid `` options. This feature leverages:pep: `768 `
118+ and the:func: `sys.remote_exec ` function to attach to the remote process
119+ and send the PDB commands to it.
120+
121+
122+ To attach to a running Python process for remote debugging, use the ``-p `` or
123+ ``--pid `` option with the target process's PID::
124+
125+ python -m pdb -p 1234
126+
127+ This will connect to the Python process with the given PID and allow you to
128+ debug it interactively. Notice that due to how the Python interpreter works,
129+ attaching to a remote process that is blocked in a system call or waiting for
130+ I/O will only work once the next bytecode instruction is executed or when the
131+ process receives a signal.
132+
107133Typical usage to execute a statement under control of the debugger is::
108134
109135 >>> import pdb