py-spy — Sampling Profiler for Python Programs

Introduction

py-spy is a sampling profiler for Python written in Rust. It reads the call stack of a running Python process at regular intervals without injecting any code or pausing the target program. This makes it safe to use in production and on processes that are already running. It was created by Ben Frederickson to provide a zero-instrumentation profiling experience for CPython.

What py-spy Does

• Samples Python call stacks at configurable intervals (default 100 Hz) from an external process
• Attaches to already-running Python processes by PID with no code changes needed
• Generates SVG flame graphs, speedscope JSON, and raw trace files for offline analysis
• Provides a real-time top-like view showing which functions consume the most CPU time
• Profiles native C extension frames alongside Python frames for full-stack visibility

Architecture Overview

py-spy runs as a separate process and reads the target Python process's memory using OS-level process inspection APIs (process_vm_readv on Linux, mach_vm_read on macOS, ReadProcessMemory on Windows). It locates the CPython interpreter state in memory, walks the frame chain to capture the current call stack, and records timestamps. Because it never injects code into the target process, it introduces zero overhead to the profiled program. The Rust implementation keeps the profiler itself fast and memory-efficient.

Self-Hosting & Configuration

• Install with pip (pip install py-spy) or download a prebuilt binary from GitHub releases
• Record a profile: py-spy record -o output.svg -- python script.py
• Attach to a running process: py-spy record --pid PID -o output.svg
• Use --format speedscope to export traces viewable in speedscope.app
• On Linux, profiling another user's process may require sudo or the SYS_PTRACE capability

Key Features

• Zero overhead on the profiled process since it reads memory externally
• Works on unmodified, already-running production processes
• Cross-platform support for Linux, macOS, and Windows
• Native frame capture shows time spent in C extensions like NumPy and pandas
• Sub-process and thread-aware profiling for multi-threaded applications

Comparison with Similar Tools

• cProfile — stdlib instrumentation profiler that slows the target; py-spy samples externally with no overhead
• memray — focuses on memory allocations; py-spy profiles CPU time and call frequency
• Scalene — combines CPU and memory profiling but requires importing a module; py-spy needs no code changes
• Pyroscope — continuous profiling platform with a server component; py-spy is a standalone CLI tool
• perf — Linux system profiler; py-spy adds Python stack unwinding so you see function names instead of addresses

FAQ

Q: Does py-spy slow down the process being profiled? A: No. It reads memory from outside the process and does not inject code, so the target runs at full speed.

Q: Can I profile a Python process running in Docker? A: Yes. Run py-spy on the host with the container's PID, or inside the container with the SYS_PTRACE capability.

Q: Does it support PyPy or GraalPy? A: No. py-spy works with CPython only, as it reads CPython-specific internal data structures.

Q: How do I read the flame graph? A: The x-axis represents the proportion of samples in each function. Wider bars mean more CPU time. The y-axis shows the call stack depth.

Sources

• https://github.com/benfred/py-spy
• https://pypi.org/project/py-spy/