py-spy: Sampling Profiler for Python
py-spy is a sampling profiler for Python programs. It visualizes where a Python process spends its time without restarting the process or modifying its code. py-spy runs in a separate process from the program it profiles and reads stack information out of the target’s memory, which keeps overhead low enough that the project documents it as safe to use against production workloads.
For workload-specific alternatives, see Which Python profiler should I use?.
Profile a running process
Use py-spy when a Python process is already running and needs to be profiled in place: a web worker under load, a data-pipeline job mid-run, a stuck process that needs a stack dump, or any CPU-bound script whose profile should not be distorted by per-function tracing overhead. py-spy is a practical default for production CPU profiling because it requires no instrumentation and can be attached and detached at will. For line-by-line attribution inside a known hot function, reach for line_profiler; for memory rather than CPU, reach for memray.
Inspect live stacks
- Out-of-process sampling: runs as a separate process and reads the target interpreter’s stacks via OS-level process inspection. The profiled program needs no
import, no decorator, and no restart. - Three subcommands:
recordwrites a profile to disk,topshows a live top-style view, anddumpprints the current Python call stack for every thread (useful for diagnosing a hung process). - Multiple output formats:
recordemits flame-graph SVG by default, Speedscope JSON via--format speedscope, Chrome trace JSON via--format chrometrace, or collapsed stacks via--format raw. The Perfetto UI accepts the Chrome trace format. - Native extension profiling: the
--nativeflag captures C, C++, and Cython frames alongside Python frames. Native support covers Linux (x86-64, ARM, Aarch64) and Windows (x86-64); the project does not claim native support on macOS. - Subprocess support:
--subprocessesfollowsmultiprocessing,subprocess.Popen, and forked workers so a process tree can be profiled as one. - GIL and idle filtering:
--gilrestricts samples to frames that hold the GIL;--idleincludes threads that are waiting on I/O. Samples can be filtered to the kind of work being investigated. - Interpreter coverage: supports CPython 2.3 through 2.7 and 3.3 through 3.15, per the project’s compatibility matrix. Support for an interpreter version does not imply support for its free-threaded build.
Install py-spy
The simplest install uses uv to place py-spy on PATH as a standalone tool:
uv tool install py-spyOther options documented by the project:
pip install py-spy # from PyPI
brew install py-spy # macOS, via Homebrew
cargo install py-spy # builds from source; needs libunwind-dev on LinuxThe project also ships in the Arch User Repository (yay -S py-spy) and the Alpine edge testing repo.
Check process permissions
py-spy runs on Linux, macOS, Windows, and FreeBSD. Attaching to a running process requires OS-level permissions to read another process’s memory, which has several practical consequences:
- macOS: the README states that attaching on macOS always requires running as root. The system Python at
/usr/bin/pythoncannot be profiled because of System Integrity Protection; a non-system Python (installed via uv, Homebrew, or pyenv) is required. - Linux: profiling a process that py-spy launched itself (
py-spy record -- python script.py) works without root. Attaching to an existing process by PID usually requiressudounless thekernel.yama.ptrace_scopesysctl has been relaxed. - Docker: the default seccomp profile blocks
process_vm_readv. Run the container with--cap-add SYS_PTRACEto allow py-spy to attach. - Kubernetes: add
SYS_PTRACEto the profiling container’ssecurityContext.capabilities.addlist underspec.containers.
Choose an output format
| Format | Flag | Viewer |
|---|---|---|
| Flame graph | default, or --format flamegraph |
Any browser (SVG) |
| Speedscope | --format speedscope |
speedscope.app |
| Chrome trace | --format chrometrace |
Perfetto UI |
| Raw | --format raw |
Custom tooling |
Use external sampling
- Requires no code changes and no process restart, which makes it practical for production debugging.
- Runs out of process, so the sampler’s own overhead is decoupled from the profiled program’s event loop or GIL.
- Captures native extension frames on Linux and Windows when built with symbols.
py-spy dumpprints live stacks, which recovers useful state from a hung or looping process where a full profile is overkill.
Account for sampling limits
- Sampling estimates time shares without recording every call. A deterministic profiler like cProfile records call counts and timings, but its instrumentation affects those timings. Very short functions may be under-sampled.
- Attaching to an existing PID depends on OS permissions and process ownership; sandboxed environments (Docker, Kubernetes, restricted containers) may need explicit capability grants.
- macOS does not support native-extension profiling per the project’s platform matrix.
- Python frames on an event-loop thread do not reconstruct asyncio task relationships. For task-aware inspection, see Austin or profiling.sampling.