py-spy

• You need to profile a running Python service without changing code or restarting it
• You want an immediate flamegraph, live top view, or one-shot thread dump from a PID
• You need to include worker subprocesses, GIL-only samples, thread IDs, or supported native extension frames
• You are diagnosing production CPU use and an in-process deterministic profiler would distort the workload

pip install py-spy normally installs a prebuilt binary wheel; the tool runs as the py-spy command and does not need to be imported into the target program. Version 0.4.2 supports recent CPython versions through 3.14 according to the README, but interpreter support and availability of a wheel are separate questions. Cargo installation builds from Rust source and on Linux or Windows requires libunwind development files. Alpine Python does not accept ordinary manylinux wheels, so upstream points to an Alpine testing package or a musl release binary rather than a normal pip path. Attaching is where setup gets operational. py-spy reads another process's memory, so Linux commonly blocks an existing PID under ptrace_scope unless the profiler has matching ownership and permission or runs with elevated privileges. Launching the target as a child of py-spy often avoids that restriction. macOS generally requires root, and System Integrity Protection can prevent profiling the system Python under /usr/bin even as root. Docker's default seccomp and capabilities block the memory-reading call; start the container with SYS_PTRACE or profile from a suitably privileged host. Kubernetes also drops SYS_PTRACE, so adding that capability changes the pod security profile and should go through the cluster's security review. Profile files can reveal function names, paths, process command lines, thread names, and, with dump --locals, application values. Treat them as potentially sensitive artifacts. By default py-spy pauses the process briefly while collecting each sample to avoid inconsistent stack reads. --nonblocking removes that pause but can increase sampling errors and partial frames, and source validation forbids combining it with --native. Sampling defaults to a rate configured by the tool; higher rates increase observation overhead and file volume, so set a bounded duration in production. Native profiling is available only on supported architectures, works best with debug symbols, and Cython line mapping needs generated C or C++ files. --gil intentionally omits extension work that releases the GIL, while --idle does the opposite of its name's common interpretation by including threads py-spy would otherwise classify as idle. For gunicorn or multiprocessing, add --subprocesses from the start so newly created children are followed. Always reproduce a hot path more than once before treating sample proportions as a precise benchmark.