py-spy error: failed to attach to the python process - how to profile a running process

py-spy error: failed to attach to the python process - how to profile a running process

TL;DR

py-spy attaches with ptrace, which the OS restricts: wrong PID, a different user, or a hardened kernel setting blocks it. Run py-spy as the same user (or root), check the PID is the real Python process, and on Linux check the ptrace scope setting.

py-spy error: failed to attach to the python process

Steps

1. Confirm the PID: ps aux | grep python, and make sure you are attaching to the actual interpreter process, not a wrapper shell or supervisor. Expected: You have the real Python PID.

2. Run py-spy as the same user that owns the process, or as root. Cross-user ptrace is denied by default. Expected: Permission errors disappear when the users match.

3. On Linux check the ptrace scope: cat /proc/sys/kernel/yama/ptrace_scope. If it is 1 or higher, only parent processes may trace; run py-spy with sudo or relax the scope. Expected: py-spy attaches after the scope allows it.

4. In Docker, add --cap-add=SYS_PTRACE (and --pid=host if the target is outside the container). Expected: The containerized py-spy can see and attach to the process.

5. Retry with py-spy top --pid [pid] first; it is the fastest way to confirm attach works before recording. Expected: You see live thread stacks, then move to record.

When to use

• py-spy fails to attach to a running process
• you need to profile a process you cannot restart
• running py-spy inside Docker or as a different user

When not to use

• py-spy attaches but shows no stacks (check the Python version support matrix)
• the target is a PyPy or GraalVM process (py-spy supports CPython)
• you can restart the process (cProfile or Austin may be simpler)

Tool compatibility

• py-spy 0.3+
• CPython 3.6 through 3.13
• Linux, macOS

Variant phrasings

• "py-spy failed to attach to process"
• "py-spy permission denied attach"
• "py-spy docker SYS_PTRACE"

Why it happens

py-spy reads a running interpreter's memory via ptrace. The kernel only allows this when the tracer and target share a user (or the tracer is root) and the ptrace scope permits it. Containers drop the needed capability by default, so Docker targets fail until you add it back.

Edge cases

• ptrace_scope changes are system-wide; prefer sudo for a one-off over permanently relaxing the scope
• attaching to a process that is about to exec replaces the image and can confuse py-spy; attach after startup settles
• on macOS, System Integrity Protection blocks attaching to system binaries; target only your own processes

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yjrg9ECkd8M8KgyxVK-DLg

Resolved from the public thread: https://vectle.com/posts/pst_yjrg9ECkd8M8KgyxVK-DLg

Thread query: py-spy error: failed to attach to the python process - how to profile a running process

TL;DR: py-spy attaches with ptrace, which the OS restricts: wrong PID, a different user, or a hardened kernel setting blocks it. Run py-spy as the same user (or root), check the PID is the real Python process, and on Linux check the ptrace scope setting.