py-spy
Sampling CPU profiler for Python — profiles running Python processes without code changes or restarts. py-spy features: py-spy top --pid PID for live top-like CPU view, py-spy record -o profile.svg --pid PID for flamegraph SVG, py-spy dump --pid PID for stack trace snapshot, zero-overhead profiling (sampling not instrumentation), native code profiling (C extensions, Cython), support for multi-threaded programs, support for subprocesses, Docker container profiling, GIL state tracking, and async task awareness. Written in Rust — profiles Python 2/3, PyPy, and embedded Python.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
py-spy reads process memory — running as root with ptrace access is a privileged operation. Use in production only with authorized access. Stack dumps may contain sensitive data (function arguments, local variables visible in frame names). Treat flamegraphs as potentially sensitive artifacts.
⚡ Reliability
Best When
Profiling running Python agents and services without modifying code or restarting — py-spy attaches to live processes (including production) for real workload profiling that development benchmarks miss.
Avoid When
You need memory profiling (use memray), line-level detail (use line_profiler), or are on Windows without ptrace support.
Use Cases
- • Agent live CPU monitoring — py-spy top --pid $(pgrep -f agent.py) — live terminal view of hottest Python functions; agent developer identifies which function consumes CPU during load spike without stopping production agent; similar to Unix top but for Python call stack
- • Agent flamegraph generation — py-spy record -o agent_flamegraph.svg --pid PID --duration 30 -- python agent.py — records 30 seconds of sampling and generates interactive SVG flamegraph; agent performance engineer visualizes CPU hotspots across all call paths; widest frames are biggest CPU consumers
- • Agent stack dump on hang — py-spy dump --pid PID — prints current stack trace of all threads; agent developer diagnoses deadlock or infinite loop by dumping state without restart; shows GIL state and whether agent is blocked in C code or Python
- • Agent process profiling without PID — py-spy record -o output.svg -- python agent_script.py — profile new process from startup; agent benchmark captures full startup and warm-up overhead not visible in attached profiling; alternative to cProfile without code modification
- • Agent Docker container profiling — docker exec -it container py-spy top --pid 1 — profile Python process inside running container; agent production profiling without container restart or code change; requires SYS_PTRACE capability in container security profile
Not For
- • Memory profiling — py-spy is CPU-only; for memory use memray or tracemalloc
- • Line-level profiling — py-spy shows function-level (frames); for line-level use line_profiler
- • Windows process attachment — py-spy top/dump attaching to existing process is limited on Windows; use on Linux/macOS for best results
Interface
Authentication
No auth — CLI tool. Requires ptrace permissions or root to attach to processes.
Pricing
py-spy is MIT licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Root or ptrace_scope=0 required on Linux — py-spy top --pid 1234 as non-root fails with 'Operation not permitted' on Linux with ptrace_scope > 0; agent developers must: sudo py-spy top --pid PID OR echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope; Docker requires --cap-add=SYS_PTRACE
- ⚠ Docker containers need SYS_PTRACE capability — py-spy inside Docker or attaching to Docker process fails without: docker run --cap-add=SYS_PTRACE container; agent profiling in container orchestration (Kubernetes) requires securityContext.capabilities.add: ['SYS_PTRACE'] in pod spec
- ⚠ Flamegraph SVG requires browser to view — py-spy record -o profile.svg generates SVG not HTML; opening in terminal fails; agent developer must copy to local machine or serve via HTTP: python -m http.server; SVG can also be converted to HTML with speedscope for better interactivity
- ⚠ Subprocesses not profiled by default — py-spy record -- python script.py profiles only main process; agent code using multiprocessing or subprocess workers not profiled; add --subprocesses flag: py-spy record --subprocesses -- python agent.py to capture all child process profiles
- ⚠ Sampling misses short functions — py-spy samples at 100 Hz by default; functions executing in <10ms may not appear in flamegraph; agent profiling of fast hot loops needs higher rate: py-spy record --rate 1000 --pid PID; higher rate increases overhead slightly
- ⚠ C extension hotspots show as opaque frames — py-spy shows Python frames; time spent in C extensions (numpy.dot, torch.matmul) appears as single frame with no C-level detail; for C-level profiling use perf or heaptrack alongside py-spy; --native flag shows C stack but requires debug symbols
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for py-spy.
Scores are editorial opinions as of 2026-03-06.