benfred /py-spy

Sampling profiler for Python programs

★ 15,645⑂ 560👁 112⑃ 479● 427▤ 24
RustMITCreated 2018-08-01
下载:v0.4.3py-spy-0.4.3 ↓0.4.32026-11-02
+0
日增长
15,645
stars
560
forks
112
watchers
479
prs
427
issues
24
releases

README

py-spy: Sampling profiler for Python programs
=====


py-spy is a sampling profiler for Python programs. It lets you visualize what your Python
program is spending time on without restarting the program or modifying the code in any way.
py-spy is extremely low overhead: it is written in Rust for speed and doesn't run
in the same process as the profiled Python program. This means py-spy is safe to use against production Python code.

py-spy works on Linux, OSX, Windows and FreeBSD, and supports profiling all recent versions of the CPython
interpreter (versions 2.3-2.7 and 3.3-3.15).

 Installation

Prebuilt binary wheels can be installed from PyPI with:


pip install py-spy


You can also download prebuilt binaries from the GitHub Releases
Page.

If you're a Rust user, py-spy can also be installed with: cargo install py-spy. Note this
builds py-spy from source and requires libunwind on Linux and Window, e.g., 
apt install libunwind-dev.

On macOS, py-spy is in Homebrew and 
can be installed with brew install py-spy.

On Arch Linux, py-spy is in AUR and can be
installed with yay -S py-spy.

On Alpine Linux, py-spy is in testing repository and
can be installed with apk add py-spy --update-cache --repository http://dl-3.alpinelinux.org/alpine/edge/testing/ --allow-untrusted.

 Usage

py-spy works from the command line and takes either the PID of the program you want to sample from
or the command line of the python program you want to run. py-spy has three subcommands
record, top and dump:

 record

py-spy supports recording profiles to a file using the record command. For example, you can
generate a flame graph of your python process by
going:

 bash
py-spy record -o profile.svg --pid 12345
 OR
py-spy record -o profile.svg -- python myprogram.py


Which will generate an interactive SVG file looking like:

!flame graph

You can change the file format to generate
speedscope profiles or raw data with the --format parameter.
See py-spy record --help for information on other options including changing
the sampling rate, filtering to only include threads that hold the GIL, profiling native C extensions,
showing thread-ids, profiling subprocesses and more.

 top

Top shows a live view of what functions are taking the most time in your python program, similar
to the Unix top command. Running py-spy with:

 bash
py-spy top --pid 12345
 OR
py-spy top -- python myprogram.py


will bring up a live updating high level view of your python program:

!console viewer demo

 dump

py-spy can also display the current call stack for each python thread with the dump command:

bash
py-spy dump --pid 12345


This will dump out the call stacks for each thread, and some other basic process info to the
console:

!dump output

This is useful for the case where you just need a single call stack to figure out where your
python program is hung on. This command also has the ability to print out the local variables
associated with each stack frame by setting the --locals flag.

 Fr

Top issues

Latest release

v0.4.3 v0.4.3 2026-11-02
Changes

 🚀 Features

- Python 3.15 support @benfred (878)
- Add Windows ARM64 wheels @ndabas (867)
- Format function names with qualname for Python 3.11+ @jake-kramer (825)
- Classify 3.12+ frames by owner and mask stackref tag bits @korniltsev-grafanista (884)
- Use \_Py\_DebugOffsets to get imports modules address @benfred (877)
- Skip thread-name lookup for outputs that do not use names @jonashaag (862)
- Gate CLI dependencies behind optional cli feature flag @korniltsev-grafanista (848)
- Add thread name lookup tests, lookup again after 1 second if not matched at first @krassow

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON