pdb-attach

What it is and what it does

pdb-attach is a remote debugger that lets you pause and inspect a long-running Python process without stopping it. You set it up by importing the module and calling `listen()` with a port number in your application code; when the process is running, you connect from another terminal using the process ID and port, and interact with pdb as usual. When done, you detach and the process continues.

The package uses signals and sockets to communicate between the debugger and the running process. It is POSIX-only (no Windows support) and requires that you instrument your code with pdb-attach before the process starts—you cannot attach to an arbitrary running Python process. The documentation warns that the socket is unauthenticated, so a local attacker could potentially connect and execute code as your user; planned features aim to mitigate this, but they are not yet implemented.

Use it for:

• Debug a long-running batch job or service without restarting it to see what state it is in.
• Inspect variables and execution flow in a production-like environment while the process continues running.
• Troubleshoot deadlocks or hangs in multi-threaded or async code by pausing and examining the call stack.
• Develop and test a daemon or background worker by attaching a debugger on demand without stopping the service.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Attaches a Python debugger (pdb) to long-running processes without restarting them, allowing interactive inspection and control via a socket connection.

Yes, if you are on POSIX and willing to instrument your code with pdb-attach before deployment. It solves a real problem—interactive debugging of long-running processes—that standard pdb cannot handle. The dormant maintenance status and lack of active security mitigations are acceptable for development and testing environments, but the unauthenticated socket and Windows incompatibility limit its scope. Install if you need remote debugging for a POSIX-based service or batch job.

Install

pdb-attach on PyPI

pip install pdb-attach

uv add pdb-attach

poetry add pdb-attach

Installing pdb-attach

Before you install

Low friction installation with no runtime dependencies. Maintenance is dormant—last release was 2023-09-23—but the repository remains active and unarchived. Suitable for projects that do not require active upstream support.

License in practice

BSD 3-Clause is permissive and poses no significant restrictions on use, modification, or distribution. Safe for both open-source and proprietary projects.

Quickstart

# In your running process:
import pdb_attach
pdb_attach.listen(50000)

# From another terminal, attach to the process:
python -m pdb_attach <pid> 50000
# Then interact with pdb normally; type 'detach' to disconnect.

POSIX-only; does not work on Windows. Must be imported and configured in the target process before it starts—cannot attach to an already-running process that did not import pdb-attach.

Verify before relying

• Whether the package works reliably on Python versions beyond 3.9 given the last release was 2023-09-23.
• Whether the planned security mitigations (secret-key signing, read-only inspection mode) have been implemented since the documentation was written.

Package facts

Evidence: pdb_attach-3.0.1-py3-none-any.whl

Keywords: pdb, debug, debugger, process

Tags

More Python Modules packages