py-spy
py-spy is a free, open-source sampling profiler for Python programs.
What py-spy is
py-spy is a free, open-source sampling profiler for Python programs. It observes a running process from outside that process, so profiling does not require restarting the program or changing its code. Its command line provides `record` to save profiles, `top` to view live activity, and `dump` to show thread call stacks. Recorded output can be a flame graph, speedscope profile, raw data, or Chrome trace. The project lists support for recent CPython versions 2.3–2.7 and 3.3–3.14, and says it can profile native extensions written in C, C++, or Cython on some platforms. The `--subprocesses` option lets `record` or `top` include child Python processes, such as multiprocessing or gunicorn workers. py-spy runs on Linux, macOS, and Windows; installation options include pip, release binaries, Cargo, Homebrew, Arch AUR, and Alpine packages. Attaching to processes may require elevated permissions. In Docker and Kubernetes, it needs the `SYS_PTRACE` capability. Nonblocking mode avoids pausing the target, but can lead to sampling errors or partial stack frames.
Good
- Profiles without restarting or changing program code
- Provides live activity and thread call stacks
- Exports several profile formats
- Supports child-process profiling
- Available on Linux, macOS, and Windows
Watch out
- Attaching may require elevated permissions
- Containers require the SYS_PTRACE capability
- Nonblocking mode may yield sampling errors
- Only the most recent version gets security updates
Who it suits
py-spy suits Python developers who need to inspect time use in a running program without restarting or modifying it. It can also help when profiling child processes or native extensions on supported platforms.
Verdict
py-spy offers a range of profiling views while leaving the target process running. Check process permissions and container requirements, and weigh the possible stack or sampling inaccuracies of nonblocking mode.
Plans and prices
From py-spy's own pricing page, checked 5 Oct 2026.
| Plan | Price | What it gives you |
|---|---|---|
| py-spy | Free | MIT-licensed; sampling profiler for Python programs |
The facts
Each one read from py-spy's own pages, with the date it was checked.
What it does
- Commands
- The command line has `record`, `top`, and `dump` subcommands for saving profiles, viewing live activity, and displaying thread call stacks.checked 5 Oct 2026
- Containers
- For Docker and Kubernetes, the README says py-spy needs the `SYS_PTRACE` capability to read process memory.checked 5 Oct 2026
- Installation
- The project documents installation through PyPI with pip, GitHub release binaries, Cargo, Homebrew, Arch AUR, and Alpine packages.checked 5 Oct 2026
- License
- The repository says py-spy is released under the MIT License.checked 5 Oct 2026
- 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.checked 5 Oct 2026
- Native extensions
- The README says py-spy can profile native Python extensions written in C, C++, or Cython on some platforms.checked 5 Oct 2026
- Nonblocking mode
- The `--nonblocking` option avoids pausing the target process, though the README notes it can cause sampling errors or partial stack frames.checked 5 Oct 2026
- 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.checked 5 Oct 2026
- Profile outputs
- `record` can create flame graphs, speedscope profiles, or raw data, and release notes also list Chrome trace format support.checked 5 Oct 2026
- Purpose
- py-spy is a sampling profiler for Python programs that visualizes where a program spends time without restarting it or changing its code.checked 5 Oct 2026
- Python support
- The README says it supports recent CPython versions 2.3–2.7 and 3.3–3.14.checked 5 Oct 2026
- Security reporting
- The security policy asks users to report vulnerabilities by email and says only the most recent version receives security updates.checked 5 Oct 2026
- Subprocesses
- With `--subprocesses`, `record` or `top` can include child Python processes, such as multiprocessing or gunicorn workers.checked 5 Oct 2026
Alternatives to py-spy
- 1
Grafana Cloud Application Observability
Free planAndroidiOSWebAPI8.4From $0.03 a month - 2
Grafana Alerting
Free planWebLinuxmacOSWindows6.8$0.03 usage-based - 3
YourKit .NET Profiler
Free planAPILinuxmacOSWindows6.8From $99 a year - 4
Amazon CodeGuru Profiler
Free planWebAPILinuxSelf-hosted6.7From $0.01 a month - 5
Pyroscope
Free planWebLinuxmacOSWindows6.7From $19 a month - 6
Parca
Free planWebAPILinuxSelf-hosted6.6Free plan