py-spy

py-spy: Sampling profiler for Python programs
=====
[![Build Status](https://github.com/benfred/py-spy/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/benfred/py-spy/actions/workflows/build.yml)

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](https://github.com/benfred/py-spy/releases).

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](https://formulae.brew.sh/formula/py-spy#default) and 
can be installed with ```brew install py-spy```.

On Arch Linux, [py-spy is in AUR](https://aur.archlinux.org/packages/py-spy/) and can be
installed with ```yay -S py-spy```.

On Alpine Linux, [py-spy is in testing repository](https://pkgs.alpinelinux.org/packages?name=py-spy&branch=edge&repo=testing) 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](http://www.brendangregg.com/flamegraphs.html) 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](./images/flamegraph.svg)

You can change the file format to generate
[speedscope](https://github.com/jlfwong/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](https://linux.die.net/man/1/top) command. Running py-spy with:

``` bash
py-spy top --pid 12345
# OR
py