+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
#242Doesn't work on OSX24 comments · 2020-05-27#210Native profiling (cython) -- merge error17 comments · 2019-12-31#823Python 3.14 - Failed to find python version from target process11 comments · 2026-01-20#530Doesn't find Python version in Docker with emulated x86/arm10 comments · 2022-10-25#553Fail with "Error: No such file or directory (os error 2)"9 comments · 2023-02-20#565py-spy thread blocks when locking the python thread8 comments · 2023-04-11#389traces include time spent in garbage collector8 comments · 2021-05-06#188Native profiling on macOS8 comments · 2019-10-28
Latest release
v0.4.3 v0.4.3 2026-11-02Changes 🚀 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