Repolode
Submit
benfred

benfred/py-spy

A sampling profiler for Python programs that attaches to running processes without modifying code or restarting them.

View on GitHub
Stars
15,628
Forks
560
Open issues
236
Last commit
12 hours ago

What is it?

py-spy lets you see where a running Python program spends its time. It samples the target process from outside, so there is no need to change the code, add imports or restart the program. It is written in Rust and runs in a separate process from the one being profiled, which keeps overhead low enough to use against production services.

The tool has three subcommands. `record` writes profiles to flame graph SVG, speedscope or raw formats, `top` shows a live, continuously updating view of the hottest functions, and `dump` prints the current call stacks of every thread, optionally with local variables. Additional options cover sampling rate, GIL-only sampling, native C/C++ or Cython extension frames, and following subprocesses such as multiprocessing or gunicorn workers.

py-spy runs on Linux, macOS, Windows and FreeBSD and supports a wide range of CPython versions. On Linux, attaching to an existing PID usually requires root or relaxed ptrace settings, and in Docker or Kubernetes the container needs the SYS_PTRACE capability.

Key features

  • 01Attaches to running Python processes by PID without code changes or restarts.
  • 02Outputs flame graphs as SVG, speedscope profiles or raw data.
  • 03Provides a live `top` view of the functions consuming the most time.
  • 04Dumps the call stack of every thread, with optional local variables.
  • 05Can filter to threads holding the GIL and profile native extensions.
  • 06Follows child processes such as multiprocessing or gunicorn workers.

Use cases

  • Finding the slow functions in a production Python service without redeploying it.
  • Diagnosing a hung process by dumping its current thread stacks.
  • Profiling a script by launching it under py-spy record.
  • Analyzing CPU hotspots in Cython or C extensions alongside Python frames.

Quick start

  1. 1

    Install the prebuilt binary from PyPI

    pip install py-spy
  2. 2

    Profile a running process and write a flame graph

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

    View a live top-style summary of a running process

    py-spy top --pid 12345

Things to know

  • Profiling another process on Linux usually requires root permissions.
  • OSX always requires root, and System Integrity Protection blocks profiling the built-in /usr/bin/python.
  • Native extension profiling via --native is only available on some platform and architecture combinations.

Topics

#profiling#performance-analysis#python#debugging#flame-graph#rust#profiler

FAQ

What is py-spy?
A sampling profiler for Python programs that attaches to running processes without modifying code or restarting them. py-spy lets you see where a running Python program spends its time. It samples the target process from outside, so there is no need to change the code, add imports or restart the program. It is written in Rust and runs in a separate process from the one being profiled, which keeps overhead low enough to use against production services.
Is py-spy free to use? What license does it have?
py-spy is open source under the MIT license. Check the license terms before using it in commercial products.
Is py-spy still maintained?
Actively maintained. The last commit to py-spy was on Nov 6, 2026.
What can I use py-spy for?
Finding the slow functions in a production Python service without redeploying it. Diagnosing a hung process by dumping its current thread stacks. Profiling a script by launching it under py-spy record. Analyzing CPU hotspots in Cython or C extensions alongside Python frames.
How do I install py-spy?
Install the prebuilt binary from PyPI: pip install py-spy Profile a running process and write a flame graph: py-spy record -o profile.svg --pid 12345 View a live top-style summary of a running process: py-spy top --pid 12345
Where can I get py-spy?
The source code and installation instructions are on GitHub: https://github.com/benfred/py-spy

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects