---
id: pdb-attach
version: "3.0.1"
license: BSD 3-Clause
license_treatment: permissive
maintenance: dormant
---

# pdb-attach — A python debugger that can attach to running processes.

License: permissive · Maintenance: dormant · Downloads: 700.6K/mo

## 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 above — 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

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

- License: BSD 3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 700.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

attach debugger to running process, pdb remote debugging, python process debugger, live debugging long-running python, interactive debugging without restart, socket-based python debugger, pdb attach running process, remote-debugging, posix-only

[View on SkillFed](https://skillfed.io/packages/pdb-attach) · [View on PyPI](https://pypi.org/project/pdb-attach/)