{"id":4740,"library":"remote-pdb","title":"Remote PDB","description":"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.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/ionelmc/python-remote-pdb","tags":["debugging","remote","pdb","telnet"],"install":[{"cmd":"pip install remote-pdb","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"remote-pdb is based on pdbx for its core debugger functionality.","package":"pdbx","optional":false}],"imports":[{"note":"This function opens a remote PDB session on the first available port by default.","symbol":"set_trace","correct":"from remote_pdb import set_trace"},{"note":"Use this class directly to specify host and port for the remote PDB session.","symbol":"RemotePdb","correct":"from remote_pdb import RemotePdb"}],"quickstart":{"code":"import os\nfrom remote_pdb import RemotePdb\n\nREMOTE_HOST = os.environ.get('REMOTE_PDB_HOST', '127.0.0.1')\nREMOTE_PORT = int(os.environ.get('REMOTE_PDB_PORT', 4444))\n\ndef my_function():\n    print(\"Entering my_function...\")\n    # This will block until a client connects\n    RemotePdb(host=REMOTE_HOST, port=REMOTE_PORT).set_trace()\n    print(\"Exiting my_function.\")\n\nif __name__ == '__main__':\n    print(f\"Starting script. Remote PDB will listen on {REMOTE_HOST}:{REMOTE_PORT}.\")\n    print(\"Connect with: telnet \" + REMOTE_HOST + \" \" + str(REMOTE_PORT))\n    my_function()\n    print(\"Script finished.\")\n\n# To run and connect:\n# 1. Start your Python script (e.g., python your_script.py)\n# 2. In another terminal, connect: telnet 127.0.0.1 4444 (or custom host/port)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"2.0.0+"},{"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`","message":"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`).","severity":"gotcha","affected_versions":"All"},{"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.","message":"If multiple threads or processes simultaneously call `set_trace()`, only one will successfully establish a debugger connection, while the others may pend or fail.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}