py-spy
github.com
- Free plan
- Windows
- macOS
- Linux
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
Plans
Every plan and pricepy-spy
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.