py-spy is a sampling profiler for Python programs written in Rust that visualizes where a Python program spends execution time without requiring code modification or program restart.
The tool solves the problem of understanding Python performance bottlenecks in running systems by sampling the call stack at intervals and analyzing where time is spent. Because it runs as a separate process written in Rust rather than instrumenting the target Python program, it achieves extremely low overhead and can safely profile production code. It works by attaching to a running Python process by its PID or by launching a new Python program and collecting stack samples, then generating visualizations of the profiling results.
Developers should choose this tool when they need to profile Python code in production environments or other scenarios where modifying code or restarting the program is impractical. It suits any project running CPython versions from 2.3 through 3.14 on Linux, macOS, Windows, or FreeBSD. The tool supports profiling native extensions written in C, C++, or Cython when compiled with symbols, which distinguishes it from pure-Python profilers. Installation is straightforward through multiple channels including PyPI wheels, Homebrew, package managers for various Linux distributions, and Cargo for Rust users.
The project maintains active build automation across multiple platforms and architectures. Development activity spans support for a wide range of Python versions and operating systems, indicating sustained maintenance across diverse environments. The tool includes multiple operational modes—recording profiles to files, displaying real-time statistics, and dumping stack information—suggesting ongoing refinement of its interface and capabilities.
