Remote PDB

2.1.0 · active · verified Sun Apr 12

Remote-pdb provides a robust, vanilla PDB (Python Debugger) interface over TCP sockets, designed for remote debugging scenarios. It handles connection failures and integrates well with CI environments. The current version is 2.1.0, and releases occur infrequently but with critical fixes and Python version support.

Warnings

breaking Starting with RemotePDB 2.0+, disconnecting from the debugger (e.g., via Ctrl-C in the client) can raise a `BdbQuit` exception in the remote process, potentially crashing the application.
Fix: Before exiting the client (e.g., via Ctrl-C, `exit`, or `quit` commands), ensure you send a `c` (continue) command within the debugger to cleanly disconnect.
gotcha When using `remote-pdb` inside a Docker container (or similar virtualized environment) and attempting to connect from the host, the `REMOTE_PDB_HOST` must be set to `0.0.0.0` (not `127.0.0.1` or `localhost`) within the container, and the port must be properly mapped (`-p host_port:container_port`).
Fix: Set the host to `0.0.0.0` in your code or via `REMOTE_PDB_HOST` environment variable, and configure Docker port mapping. Example: `REMOTE_PDB_HOST=0.0.0.0 python script.py` and `docker run -p 4444:4444 my_image`
gotcha If multiple threads or processes simultaneously call `set_trace()`, only one will successfully establish a debugger connection, while the others may pend or fail.
Fix: Ensure that `set_trace()` is called in a controlled manner, ideally only by the specific thread/process you intend to debug, or implement a mechanism to serialize debugger access for multi-threaded/multi-process applications.
gotcha The `RemotePdb` constructor, or `set_trace()` when invoked without arguments (relying on automatic port selection), will block execution of the remote program until a client successfully connects.
Fix: Be aware that program execution will pause indefinitely at the `set_trace()` call until a telnet or similar client connects. This is by design, but can be a 'gotcha' if not expected.
gotcha Setting `REMOTE_PDB_QUIET=1` to suppress output will prevent `remote-pdb` from printing the ephemeral port number when `set_trace()` is used without explicitly specifying a port.
Fix: When `REMOTE_PDB_QUIET=1` is set, you must also explicitly set `REMOTE_PDB_PORT` via an environment variable or `RemotePdb` constructor to know which port to connect to.

Install

pip install remote-pdb Install latest version

Imports

set_trace
```
from remote_pdb import set_trace
```
This function opens a remote PDB session on the first available port by default.
RemotePdb
```
from remote_pdb import RemotePdb
```
Use this class directly to specify host and port for the remote PDB session.

Quickstart

This example demonstrates how to set up a remote PDB session that listens on a specified host and port. The `set_trace()` call will block execution until a `telnet` client connects. For Python 3.7+, you can also use the built-in `breakpoint()` by setting the `PYTHONBREAKPOINT=remote_pdb.set_trace` environment variable, along with `REMOTE_PDB_HOST` and `REMOTE_PDB_PORT` for configuration.

import os
from remote_pdb import RemotePdb

REMOTE_HOST = os.environ.get('REMOTE_PDB_HOST', '127.0.0.1')
REMOTE_PORT = int(os.environ.get('REMOTE_PDB_PORT', 4444))

def my_function():
    print("Entering my_function...")
    # This will block until a client connects
    RemotePdb(host=REMOTE_HOST, port=REMOTE_PORT).set_trace()
    print("Exiting my_function.")

if __name__ == '__main__':
    print(f"Starting script. Remote PDB will listen on {REMOTE_HOST}:{REMOTE_PORT}.")
    print("Connect with: telnet " + REMOTE_HOST + " " + str(REMOTE_PORT))
    my_function()
    print("Script finished.")

# To run and connect:
# 1. Start your Python script (e.g., python your_script.py)
# 2. In another terminal, connect: telnet 127.0.0.1 4444 (or custom host/port)

view raw JSON →