Text of peps.python.org › pep-0768 as Styx crawled it on Oct 13, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 768 – Safe external debugger interface for CPython | peps.python.org

PEP 768 – Safe external debugger interface for CPython PEP 768 – Safe external debugger interface for CPython Author : Pablo Galindo Salgado <pablogsal at python.org>, Matt Wozniski <godlygeek at gmail.com>, Ivona Stojanovic <stojanovic.i at hotmail.com> Discussions-To : Discourse thread Status : Final Type : Standards Track Created : 25-Nov-2024 Python-Version : 3.14 Post-History : 11-Dec-2024 Resolution : 17-Mar-2025 Table of Contents Abstract Motivation Rationale Specification Runtime State Extensions Debug Offsets Table Attachment Protocol Interpreter Integration Python API Configuration API Multi-threading Considerations Backwards Compatibility Security Implications Security scenarios How to Teach This Reference Implementation Rejected Ideas Writing Python code into the buffer Using a Single Runtime Buffer Thanks Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at Remote debugging attachment protocol . × See PEP 1 for how to propose changes. Abstract This PEP proposes adding a zero-overhead debugging interface to CPython that allows debuggers and profilers to safely attach to running Python processes. The interface provides safe execution points for attaching debugger code without modifying the interpreter’s normal execution path or adding runtime overhead.

A key application of this interface will be enabling pdb to attach to live processes by process ID, similar to gdb -p , allowing developers to inspect and debug Python applications interactively in real-time without stopping or restarting them. Motivation Debugging Python processes in production and live environments presents unique challenges. Developers often need to analyze application behavior without stopping or restarting services, which is especially crucial for high-availability systems.

Common scenarios include diagnosing deadlocks, inspecting memory usage, or investigating unexpected behavior in real-time. Very few Python tools can attach to running processes, primarily because doing so requires deep expertise in both operating system debugging interfaces and CPython internals. While C/C++ debuggers like GDB and LLDB can attach to processes using well-understood techniques, Python tools must implement all of these low-level mechanisms plus handle additional complexity.

For example, when GDB needs to execute code in a target process, it: Uses ptrace to allocate a small chunk of executable memory (easier said than done) Writes a small sequence of machine code - typically a function prologue, the desired instructions, and code to restore registers Saves all the target thread’s registers Changes the instruction pointer to the injected code Lets the process run until it hits a breakpoint at the end of the injected code Restores the original registers and continues execution Python tools face this same challenge of code injection, but with an additional layer of complexity.

Not only do they need to implement the above mechanism, they must also understand and safely interact with CPython’s runtime state, including the interpreter loop, garbage collector, thread state, and reference counting system. This combination of low-level system manipulation and deep domain specific interpreter knowledge makes implementing Python debugging tools exceptionally difficult. The few tools (see for example DebugPy and Memray ) that do attempt this resort to suboptimal and unsafe methods, using system debuggers like GDB and LLDB to forcefully inject code.

This approach is fundamentally unsafe because the injected code can execute at any point during the interpreter’s execution cycle - even during critical operations like memory allocation, garbage collection, or thread state management. When this happens, the results are catastrophic: attempting to allocate memory while already inside malloc() causes crashes, modifying objects during garbage collection corrupts the interpreter’s state, and touching thread state at the wrong time leads to deadlocks.

Various tools attempt to minimize these risks through complex workarounds, such as spawning separate threads for injected code or carefully timing their operations or trying to select some good points to stop the process. However, these mitigations cannot fully solve the underlying problem: without cooperation from the interpreter, there’s no way to know if it’s safe to execute code at any given moment. Even carefully implemented tools can crash the interpreter because they’re fundamentally working against it rather than with it.

Rationale Rather than forcing tools to work around interpreter limitations with unsafe code injection, we can extend CPython with a proper debugging interface that guarantees safe execution. By adding a few thread state fields and integrating with the interpreter’s existing evaluation loop, we can ensure debugging operations only occur at well-defined safe points. This eliminates the possibility of crashes and corruption while maintaining zero overhead during normal execution.

The key insight is that we don’t need to inject code at arbitrary points - we just need to signal to the interpreter that we want code executed at the next safe opportunity. This approach works with the interpreter’s natural execution flow rather than fighting against it. After describing this idea to the PyPy development team, this proposal has already been implemented in PyPy , proving both its feasibility and effectiveness.

Their implementation demonstrates that we can provide safe debugging capabilities with zero runtime overhead during normal execution. The proposed mechanism not only reduces risks associated with current debugging approaches but also lays the foundation for future enhancements. For instance, this framework could enable integration with popular observability tools, providing real-time insights into interpreter performance or memory usage.

One compelling use case for this interface is enabling pdb to attach to running Python processes, similar to how gdb allows users to attach to a program by process ID ( gdb -p <pid> ). With this feature, developers could inspect the state of a running application, evaluate expressions, and step through code dynamically. This approach would align Python’s debugging capabilities with those of other major programming languages and debugging tools that support this mode.

Specification This proposal introduces a safe debugging mechanism that allows external processes to trigger code execution in a Python interpreter at well-defined safe points. The key insight is that rather than injecting code directly via system debuggers, we can leverage the interpreter’s existing evaluation loop and thread state to coordinate debugging operations. The mechanism works by having debuggers write to specific memory locations in the target process that the interpreter then checks during its normal execution cycle.

When the interpreter detects that a debugger wants to attach, it executes the requested operations only when it’s safe to do so - that is, when no internal locks are held and all data structures are in a consistent state. Runtime State Extensions A new structure is added to PyThreadState to support remote debugging: typedef struct { int debugger_pending_call ; char debugger_script_path [...]; } _PyRemoteDebuggerSupport ; This structure is appended to PyThreadState , adding only a few fields that are never accessed during normal execution .

The debugger_pending_call field indicates when a debugger has requested execution, while debugger_script_path provides a filesystem path to a Python source file (.py) that will be executed when the interpreter reaches a safe point. The path must point to a Python source file, not compiled Python code (.pyc) or any other format. The size of debugger_script_path will be a trade-off between binary size and how big debugging scripts’ paths can be.

To limit the memory overhead per thread we wi

The rest of this page is on the live site.