py-spy

Installation and Setup

Install from PyPI:

• Windows
• Linux + macOS

(venv) PS> py -m pip install py-spy
(venv) PS> py-spy --version

(venv) $ python -m pip install py-spy
(venv) $ py-spy --version

Key Features

• Attaches to running Python processes or launches new ones without modifying code or restarting.
• Provides low-overhead sampling, runs outside the target process, and is suitable for production.
• Offers live views and offline recordings that generate flame graphs, speedscope profiles, Chrome trace files, and raw sample data.
• Dumps the current call stack of every thread in a running process, which helps you inspect a hung or stuck program without recording a profile.
• Supports profiling native extension frames with --native and for following child processes with --subprocesses.
• Provides flexible filtering and control including sampling rate, GIL holders only, idle threads, and per thread details.

Usage

Profile a running process and write a flame graph:

$ py-spy record -o profile.svg -p <PID>

Launch a program under the profiler:

$ py-spy record -o profile.svg -- python script.py

Watch hot functions live:

$ py-spy top -p <PID>
$ # Or
$ py-spy top -- python script.py

Dump the current call stacks of a running process:

$ py-spy dump --pid <PID>

Related Resources

Tutorial

Python's Sampling Profiler: Low-Overhead Profiling With profiling.sampling

Explore Python 3.15's new sampling profiler and learn low-overhead profiling of scripts, threads, and live production processes.

advanced python

For additional information on related topics, take a look at the following resources:

• Profiling in Python: How to Find Performance Bottlenecks (Tutorial)
• Profiling Performance in Python (Course)
• Python 3.12 Preview: Support For the Linux perf Profiler (Tutorial)
• Python 3.15 Preview: Sampling Profiler (Quiz)
• Profiling in Python: How to Find Performance Bottlenecks (Quiz)