{"id":6764,"library":"pdb-attach","title":"PDB Attach","description":"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.","status":"active","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/smitchell556/pdb-attach","tags":["debugger","attach","pdb","remote-debugging","troubleshooting","python"],"install":[{"cmd":"pip install pdb-attach","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Used in the target program to enable remote attachment.","symbol":"listen","correct":"from pdb_attach import listen"},{"note":"Command-line utility to attach to a listening process.","symbol":"pdb_attach (command)","correct":"pdb_attach <PID> <PORT>"}],"quickstart":{"code":"import pdb_attach\nimport time\nimport os\n\ndef my_long_running_function():\n    print(f\"Process PID: {os.getpid()}\")\n    print(\"Starting long-running function...\")\n    pdb_attach.listen(port=5555)\n    print(\"pdb_attach is listening on port 5555. Attach with: pdb_attach PID 5555\")\n    for i in range(100):\n        # Simulate work\n        time.sleep(1)\n        if i % 10 == 0:\n            print(f\"Iteration {i}\")\n    print(\"Function finished.\")\n\nif __name__ == \"__main__\":\n    my_long_running_function()","lang":"python","description":"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."},"warnings":[{"fix":"Use a POSIX-compliant OS (Linux, macOS) for `pdb-attach`, or explore alternative debugging tools for Windows.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Only use `pdb-attach` in secure, controlled environments. Be aware of the risks when debugging processes on machines with untrusted access.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be cautious when using in multi-threaded contexts. Consider alternative debugging strategies or carefully test its behavior with your specific multi-threaded code.","message":"pdb-attach may not work correctly in multi-threaded Python applications. Breakpoints and debugging behavior can be inconsistent across threads.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid using `pdb-attach` across container/host boundaries. Debug processes within the same container or on the host directly.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}