py-spy

Project Overview

py-spy is a sampling profiler for Python programs, written in Rust for speed. It visualizes where your Python program spends time without restarting the process or modifying code. Running out-of-process with extremely low overhead, it is safe to use against production Python services. It records flame graphs, shows a live top view, and dumps thread call stacks, working on Linux, macOS, Windows, and FreeBSD.

See what a live Python process is busy with, no restart or code changes.

Key Features

• Flame graph recording: the record command produces interactive SVG flame graphs
• Live top view: the top command shows the hottest functions in real time
• Stack dumps: the dump command prints each thread's current call stack for hang diagnosis
• Attach by PID: profile running processes directly via PID
• Native extensions: --native profiles C/C++ and Cython extensions on some platforms
• Subprocesses: --subprocesses includes child processes in profiling
• GIL filtering: optionally sample only threads holding the GIL
• Export formats: speedscope and raw data formats supported

Target Audience

• Backend developers
• SRE and operations engineers
• Teams debugging production performance
• Data pipeline developers
• Owners of Python services

Quick Start

1. Install py-spy

pip install py-spy

2. Record a flame graph

py-spy record -o profile.svg --pid 12345

3. Watch hot functions live

py-spy top --pid 12345

4. Dump stacks when the program hangs

py-spy dump --pid 12345

Core Advantages

• Production safe: out-of-process sampling with minimal overhead
• Zero intrusion: no restarts or code modifications required
• Easy install: prebuilt wheels via pip, brew, and more

System Requirements

Notes

• Platform limits: --native extension profiling is available only on some platforms
• Symbols help: compile native extensions with symbols for best results
• Permissions: attaching to production processes usually needs system privileges