py-spy
Profile running Python programs
TLDR
Show a live view of the functions that take the most execution time of a running process
Start a program and show a live view of the functions that take the most execution time
Produce an SVG flame graph of the function call execution time
Dump the call stack of a running process
SYNOPSIS
py-spy command [options]
PARAMETERS
record
Records a profile of the specified Python process to a file.
dump
Dumps the stack traces of the specified Python process to stdout.
top
Displays a real-time view of the top Python functions being executed.
--pid pid
The PID of the Python process to profile.
--name name
The name of the Python program to profile.
--native
Profile native extensions as well as Python code.
This requires debug symbols to be installed.
--rate rate
Sampling rate (samples/sec). Defaults to 100.
--output filename
Output file for the profile. Supports .svg (flamegraph), .json (speedscope), or text.
--duration seconds
Duration to record profile for in seconds. Defaults to indefinitely.
--gil-only
Only samples when the GIL is held.
DESCRIPTION
py-spy is a sampling profiler for Python programs. It lets you visualize what your Python program is spending time on without modifying the program itself or restarting it. Py-spy is written in Rust for speed and doesn't have any Python dependencies making it safe to use on production Python code. It supports profiling any Python process including those running in Docker containers. Py-spy works by sampling the stack frames of the Python process at a regular interval (default is 100 times per second) and then aggregating these samples to produce a profile. This profile can be visualized in a variety of ways, including using tools like speedscope or flamegraph. Unlike traditional Python profilers (like cProfile) py-spy does not need to be imported into the target process and doesn't introduce any performance overhead as it works by directly reading memory using the operating system's debugging APIs.
CAVEATS
py-spy requires sufficient permissions to read the memory of the target process.
This typically means running py-spy as root or with `CAP_SYS_PTRACE` capability.
Accuracy of profiling depends on the sampling rate and the duration of the profiling session.
The native profiling option requires debug symbols to be available for native extensions.
INSTALLATION
py-spy can be installed via pip: `pip install py-spy` or using cargo: `cargo install py-spy`.
FLAME GRAPHS
Flame graphs are a common visualization of profiling data showing the call stack of a program over time. py-spy can generate flame graphs directly using the `--output` option with a `.svg` extension.
HISTORY
py-spy was developed to provide a low-overhead, non-invasive way to profile Python applications, especially in production environments.
It addresses the limitations of traditional Python profilers which can introduce significant performance overhead or require code modifications.
Written in Rust, it aims for efficiency and minimal impact on the profiled application.