Skip to main content

Remote vanilla PDB (over TCP sockets) *done right*: no extras, proper handling around connection failures and CI. Based on `pdbx <>`_.

Project description

Remote vanilla PDB (over TCP sockets) done right: no extras, proper handling around connection failures and CI. Based on pdbx.

  • Free software: BSD 2-Clause License


pip install remote-pdb


To open a remote PDB on first available port:

from remote_pdb import set_trace
set_trace() # you'll see the port number in the logs

To use some specific host/port:

from remote_pdb import RemotePdb
RemotePdb('', 4444).set_trace()

To connect just run telnet 4444. When you are finished debugging, either exit the debugger, or press Control-], then Control-d.

Alternately, one can connect with NetCat: nc -C 4444 or Socat: socat readline tcp: (for line editing and history support). When finished debugging, either exit the debugger, or press Control-c.

Note that newer Ubuntu disabled readline support in socat, so if you get unknown device/address "readline" try using rlwrap like this:

rlwrap socat - tcp:

Using in containers

If you want to connect from the host to remote-pdb running inside the container you should make sure that:

  • The port you will use is mapped (eg: -p 4444:4444).

  • The host is set to (localhost` or `` will not work because Docker doesn’t map the port on the local interface).

Integration with breakpoint() in Python 3.7+

If you are using Python 3.7 one can use the new breakpoint() built in to invoke remote PDB. In this case the following environment variable must be set:


The debugger can then be invoked as follows, without any imports:


As the breakpoint() function does not take any arguments, environment variables can be used to specify the host and port that the server should listen to. For example, to run in such a way as to make telnet 4444 the correct way of connecting, one would run:


If REMOTE_PDB_HOST is omitted then a default value of will be used. If REMOTE_PDB_PORT is omitted then the first available port will be used. The connection information will be logged to the console, as with calls to remote_pdb.set_trace().

To quiet the output, set REMOTE_PDB_QUIET=1, this will prevent RemotePdb from producing any output – you’ll probably want to specify REMOTE_PDB_PORT as well since the randomized port won’t be printed.

Note about OS X

In certain scenarios (backgrounded processes) OS X will prevent readline to be imported (and readline is a dependency of pdb). A workaround (run this early):

import signal
signal.signal(signal.SIGTTOU, signal.SIG_IGN)

See #9 and cpython#14892.


Python 2.6, 2.7, 3.2, 3.3 and PyPy are supported.

Similar projects


2.1.0 (2020-07-24)

  • Changed logging to use remote_pdb logger instead of the root one. Contributed by Terence Honles in #24.

2.0.0 (2019-07-31)

  • Fixed inconsistency with normal use of pdb - BdbQuit will now be raised on quitting. Contributed by Anthony Sottile in #18. BACKWARDS INCOMPATIBLE.

  • Added REMOTE_PDB_QUIET=1 to silence output. Contributed by Anthony Sottile in #19.

1.3.0 (2019-03-13)

  • Documented support for Python 3.7’s breakpoint().

  • Added support for setting the socket listening host/port through the REMOTE_PDB_HOST/REMOTE_PDB_PORT environment variables. Contributed by Matthew Wilkes in #14.

  • Removed use of rw file wrappers around sockets (turns out socket’s makefile is very buggy in Python 3.6 and later - output is discarded). Contributed in #13.

1.2.0 (2015-09-26)

  • Always print/log listening address.

1.1.3 (2015-07-06)

  • Corrected the default frame tracing starts from.

1.1.2 (2015-07-06)

  • Small readme update.

1.1.1 (2015-07-06)

  • Remove bogus remote_pdb console script.

1.1.0 (2015-06-21)

  • Fixed buffering issues when running on Python 3 and Windows.

1.0.0 (2015-06-15)

  • Added support for PDB++.

0.2.1 (2014-03-07)

  • First release on PyPI.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

remote-pdb-2.1.0.tar.gz (22.3 kB view hashes)

Uploaded Source

Built Distribution

remote_pdb-2.1.0-py2.py3-none-any.whl (6.3 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page