remote-pdb

library2.1.0pypypi✓ verified 24d ago

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.

testing observability

pip install remote-pdb

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · REMOTE-PDB

remote-pdb

testingpythonv2.1.0

Install

1.5s avg

Import

113ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.122s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.104s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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)

Debug

Known issues

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

affects: 2.0.0+

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

affects: All

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

affects: All

gotchaThe `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.

affects: All

gotchaSetting `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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'remote-pdb'

The 'remote-pdb' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install remote-pdb'.

ImportError: cannot import name 'RemotePdb' from 'remote_pdb'

The 'remote_pdb' module is not installed or the import statement is incorrect.

fix

Ensure the module is installed with 'pip install remote-pdb' and use the correct import: 'from remote_pdb import RemotePdb'.

ConnectionRefusedError: [Errno 111] Connection refused

The remote-pdb server is not running or is not accessible at the specified host and port.

fix

Verify that the remote-pdb server is running and listening on the correct host and port, and that the network allows connections.

BdbQuit

Disconnecting from the debugger (e.g., via Ctrl-C) raises a 'BdbQuit' exception in the remote process, potentially crashing the application.

fix

Before exiting the client, send a 'c' (continue) command within the debugger to cleanly disconnect.

OSError: [Errno 98] Address already in use

The specified port for remote-pdb is already in use by another process.

fix

Choose a different port or ensure that the port is free before starting remote-pdb.

Upgrade

Version history

2.1.0latest on PyPI · released Jul 24, 2020

Audit

Dependencies

pdbxrequiredremote-pdb is based on pdbx for its core debugger functionality.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ionelmc/python-remote-pdb ↗

packagehttps://pypi.org/project/remote-pdb/ ↗

docshttps://python-remote-pdb.readthedocs.io/ ↗

changeloghttps://python-remote-pdb.readthedocs.io/en/latest/changelog.html ↗