Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

py-spy

github.com

  • Free plan
  • Windows
  • macOS
  • Linux
7.2 Club score Visit github.com

What py-spy is

py-spy is a free, MIT-licensed sampling profiler for Python programs on Linux, macOS, and Windows. It observes a running process externally, so profiling does not require restarting the program or changing its code. The command line provides `record` for saved profiles, `top` for live activity, and `dump` for thread call stacks. Output can include flame graphs, speedscope profiles, raw data, and Chrome traces. The project lists recent CPython support from 2.3–2.7 and 3.3–3.14, and says native extensions written in C, C++, or Cython can be profiled on some platforms. With `--subprocesses`, `record` and `top` can include child Python processes such as multiprocessing or gunicorn workers. Installation is documented through pip, release binaries, Cargo, Homebrew, Arch AUR, and Alpine packages. Attaching may require elevated permissions: macOS always needs root, while Linux commonly needs root for non-child processes. Docker and Kubernetes require `SYS_PTRACE`. Nonblocking mode avoids pausing the target but may produce sampling errors or partial stack frames.

Who it suits

py-spy suits Python developers and operators who need sampling profiles from running processes. It is relevant to desktop, server, container, and multi-process Python environments.

Good to know, and what to watch

  • Profiles without restarting or changing code
  • Supports Linux, macOS, and Windows
  • Exports several profile formats
  • Can include child Python processes
  • Open-source MIT licence
  • Process attachment may require root
  • Containers require SYS_PTRACE capability
  • Nonblocking mode can produce partial frames
  • Native extension support varies by platform

py-spy

Free

Open source

The verdict

py-spy offers external sampling with useful live, saved, and call-stack views. Permission requirements and nonblocking-mode limitations matter when profiling production or containerized workloads.

What the maker publishes

Commands
The command line has `record`, `top`, and `dump` subcommands for saving profiles, viewing live activity, and displaying thread call stacks. source
Containers
For Docker and Kubernetes, the README says py-spy needs the `SYS_PTRACE` capability to read process memory. source
Installation
The project documents installation through PyPI with pip, GitHub release binaries, Cargo, Homebrew, Arch AUR, and Alpine packages. source
License
The repository says py-spy is released under the MIT License. source
Low overhead
It is written in Rust and runs outside the profiled Python process, which the project says makes it safe to use against production Python code. source
Native extensions
The README says py-spy can profile native Python extensions written in C, C++, or Cython on some platforms. source
Nonblocking mode
The `--nonblocking` option avoids pausing the target process, though the README notes it can cause sampling errors or partial stack frames. source
Permissions
Attaching to a process may require elevated permissions; the README says macOS always requires root and Linux commonly requires root when attaching to a non-child process. source
Profile outputs
`record` can create flame graphs, speedscope profiles, or raw data, and release notes also list Chrome trace format support. source
Purpose
py-spy is a sampling profiler for Python programs that visualizes where a program spends time without restarting it or changing its code. source
Python support
The README says it supports recent CPython versions 2.3–2.7 and 3.3–3.14. source
Security reporting
The security policy asks users to report vulnerabilities by email and says only the most recent version receives security updates. source
Subprocesses
With `--subprocesses`, `record` or `top` can include child Python processes, such as multiprocessing or gunicorn workers. source

Checked against the maker's pages on 5 Oct 2026.