Remote debugging attachment protocol — Python 3.15.2 documentation
Navigation index modules | next | previous | Python » 3.15.2 documentation » Python HOWTOs » Remote debugging attachment protocol | Theme | Remote debugging attachment protocol ¶ This protocol enables external tools to attach to a running CPython process and execute Python code remotely. Attaching to another Python process may require additional permissions or configuration, depending on the platform. Disabling remote debugging ¶ To disable remote debugging support, use any of the following: Set the PYTHON_DISABLE_REMOTE_DEBUG environment variable to 1 before starting the interpreter.
Use the -X disable-remote-debug command-line option. Compile Python with the --without-remote-debug build flag. Permission requirements ¶ Attaching to a running Python process for remote debugging requires special configuration on most platforms. The specific requirements and troubleshooting steps depend on your operating system: Linux In general, you can debug your own processes, but there are several common configurations that may disable this.
Some Linux distributions enable ptrace restrictions , aka "Yama," as a form of system hardening. Recent versions of the setpriv command (util-linux 2.41, released June 2025) let you loosen ptrace restrictions on a per-process basis: setpriv --ptracer any python3 (This is configured on the process being debugged .) You can also turn off ptrace restrictions for all processes until reboot with: echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope This can also be configured persistently, usually in /etc/sysctl.d .
Note Disabling ptrace_scope reduces system hardening and should only be done in low-security environments. It is also possible that the ptrace system call is disabled because of a security filter. In particular, this was common with older versions of some container software. Docker 19.03 or newer (released 2019) and containerd 1.6.7 or newer (released 2022) will automatically allow usage of the ptrace system call inside containers, when running on Linux kernel 4.8 or higher.
If you cannot upgrade to these versions, you can create your container with an option like --security-opt seccomp=unconfined to disable the system call security filter for that container. This weakens the container's isolation and should only be done in low-security environments. If you need to trace a process that you do not own, you will need superuser access or equivalent. This also applies to processes that have changed their security credentials, e.g., set-user-ID or set-group-ID processes (though this is unusual for Python).
Try running the debugging command with sudo -E . Note The CAP_SYS_PTRACE capability is equivalent to superuser access, in that it allows debugging any process, not just your own. You may see advice on the internet suggesting using it to work around ptrace restrictions or system call filters. This may work in practice, as would sudo , but this gives the debugging process much more access than it needs and should only be done in low-security environments.
Finally, note that a process can only have one tracer at a time. If you have already attached to a Python process under strace , gdb , etc., you won't be able to simultaneously use remote debugging. (Superuser access cannot get around this restriction.) macOS By default, macOS disables the ability to debug other processes. You can modify your Python binary to opt in to being debugged by giving it an ad-hoc code signature with an entitlement enabling it to be debugged. (An ad-hoc "signature" is just a configuration without any actual cryptographic signature or a need for a certificate or anything else such as an Apple developer program membership.) The following commands will create a file get-task-allow.plist with the necessary entitlement and add it to the Python binary: echo '{"com.apple.security.get-task-allow": true}' | plutil -convert xml1 -o get-task-allow.plist - codesign --sign - --entitlements get-task-allow.plist path/to/bin/python3 where path/to/bin/python3 is the path to your Python binary, which you can find by e.g. running which python3 or evaluating sys._base_executable at the Python REPL. (These instructions are for a non-framework build of Python.
Framework builds may need to be configured differently.) You should then be able to debug your own Python processes started with that binary. Alternatively, much as with Linux, processes with superuser privileges e.g. sudo are not subject to this check and can debug any user's process on the system (though there are additional checks on specific binaries, such as OS-provided commands, due to System Integrity Protection).
Windows To attach to another process, you usually need to run your debugging tool with administrative privileges. Start the command prompt or terminal as Administrator. Some processes may still be inaccessible even with Administrator rights, unless you have the SeDebugPrivilege privilege enabled. To resolve file or folder access issues, adjust the security permissions: Right-click the file or folder and select Properties .
Go to the Security tab to view users and groups with access. Click Edit to modify permissions. Select your user account. In Permissions , check Read or Full control as needed. Click Apply , then OK to confirm. Note Ensure you've satisfied all Permission requirements before proceeding. This section describes the low-level protocol that enables external tools to inject and execute a Python script within a running CPython process.
This mechanism forms the basis of the sys.remote_exec() function, which instructs a remote Python process to execute a .py file. However, this section does not document the usage of that function. Instead, it provides a detailed explanation of the underlying protocol, which takes as input the pid of a target Python process and the path to a Python source file to be executed. This information supports independent reimplementation of the protocol, regardless of programming language.
Warning The execution of the injected script depends on the interpreter reaching a safe evaluation point. As a result, execution may be delayed depending on the runtime state of the target process. Once injected, the script is executed by the interpreter within the target process the next time a safe evaluation point is reached. This approach enables remote execution capabilities without modifying the behavior or structure of the running Python application.
Subsequent sections provide a step-by-step description of the protocol, including techniques for locating interpreter structures in memory, safely accessing internal fields, and triggering code execution. Platform-specific variations are noted where applicable, and example implementations are included to clarify each operation. Locating the PyRuntime structure ¶ CPython places the PyRuntime structure in a dedicated binary section to help external tools find it at runtime.
The name and format of this section vary by platform. For example, .PyRuntime is used on ELF systems, and __DATA,__PyRuntime is used on macOS. Tools can find the offset of this structure by examining the binary on disk. The PyRuntime structure contains CPython’s global interpreter state and provides access to other internal data, including the list of interpreters, thread states, and debugger support fields. To work with a remote Python process, a debugger must first find the memory address of the PyRuntime structure in the target process.
This address can’t be hardcoded or calculated from a symbol name, because it depends on where the operating system loaded the binary. The method for finding PyRuntime depends on the platform, but the steps are the same in general: Find the base address where the Python binary or shared library was loaded in the target process. Use the on-disk binary to locate the offset of the .PyRuntime section. Add the section offset to the base address to compute the address in memory.
The sections below explain how to do th
The rest of this page is on the live site.