PDB Attach

3.0.1 · active · verified Wed Apr 15

pdb-attach is a Python debugger extension that allows users to attach to already running Python processes. Unlike standard `pdb.set_trace()`, it facilitates debugging long-running or unresponsive applications by enabling remote connection. It's currently at version 3.0.1 and appears to be actively maintained, with a focus on POSIX-compliant operating systems.

Warnings

breaking pdb-attach does not work on Windows operating systems. It relies on POSIX signals for its implementation, which are not available on Windows. Although it can be imported on Windows, the `listen` function will not operate, and a warning will be raised.
Fix: Use a POSIX-compliant OS (Linux, macOS) for `pdb-attach`, or explore alternative debugging tools for Windows.
gotcha The target Python process must explicitly import and call `pdb_attach.listen()` *before* you can attach to it. It cannot attach to an arbitrary, unprepared running Python process.
Fix: Modify the target application's code to include `from pdb_attach import listen; listen(port=<some_port>)` at the point where you wish to enable attachment.
gotcha Using `pdb-attach` introduces a potential security risk. It uses sockets for communication, meaning that a malicious actor with access to your machine could connect to the debugging port, inspect the running process's source code and state, and even execute arbitrary Python code.
Fix: Only use `pdb-attach` in secure, controlled environments. Be aware of the risks when debugging processes on machines with untrusted access.
gotcha pdb-attach may not work correctly in multi-threaded Python applications. Breakpoints and debugging behavior can be inconsistent across threads.
Fix: Be cautious when using in multi-threaded contexts. Consider alternative debugging strategies or carefully test its behavior with your specific multi-threaded code.
gotcha When running inside a container (e.g., Docker) and attempting to attach to a host process, `pdb-attach` might cause segmentation faults due to `ptrace(2)` relying on `struct user_regs_struct` definitions that vary between platforms.
Fix: Avoid using `pdb-attach` across container/host boundaries. Debug processes within the same container or on the host directly.

Install

pip install pdb-attach Install stable version

Imports

listen
```
from pdb_attach import listen
```
Used in the target program to enable remote attachment.
pdb_attach (command)
```
pdb_attach <PID> <PORT>
```
Command-line utility to attach to a listening process.

Quickstart

To use `pdb-attach`, the target Python program must first be modified to call `pdb_attach.listen()` at the desired point where debugging should be enabled. This function sets up a listening socket. Then, from a separate terminal, the `pdb_attach` command-line tool is used with the target process's PID and the specified port to initiate a debugging session.

import pdb_attach
import time
import os

def my_long_running_function():
    print(f"Process PID: {os.getpid()}")
    print("Starting long-running function...")
    pdb_attach.listen(port=5555)
    print("pdb_attach is listening on port 5555. Attach with: pdb_attach PID 5555")
    for i in range(100):
        # Simulate work
        time.sleep(1)
        if i % 10 == 0:
            print(f"Iteration {i}")
    print("Function finished.")

if __name__ == "__main__":
    my_long_running_function()

view raw JSON →