py-spy

py-spy is a free, open-source sampling profiler for Python applications that shows where a running program spends time without requiring a restart or code changes. It suits developers and operators who need CPU and thread insight from live processes, particularly when production safety and multiple profile formats matter.

Overview

py-spy runs outside the Python process and is written in Rust, keeping its profiling approach low-overhead and suitable for inspecting production code. Its sampling model is designed for locating time-consuming paths rather than tracing every event, so it offers a practical view of activity with less intrusion than instrumentation-heavy approaches. The tool can attach to an already-running program, which is useful when reproducing a performance problem or restarting a service is undesirable.

The project supports recent CPython releases from 2.3 through 2.7 and 3.3 through 3.14. That unusually broad range makes it relevant to both maintained systems and older Python deployments. Native extensions written in C, C++, or Cython can also be profiled on some platforms, extending visibility beyond pure Python code, although support is platform-dependent.

Key features

Three command-line views

record saves a profile for later analysis, top presents live activity, and dump prints thread call stacks. This division covers retrospective investigation, quick monitoring, and point-in-time stack inspection without forcing every workflow into one interface.

Portable profile outputs

record can produce flame graphs, speedscope profiles, and raw data; release notes also identify Chrome trace format support. Flame graphs help expose hot call paths, while speedscope and Chrome trace outputs fit viewers and tracing workflows that already use those formats. Raw data is the better choice when you need to process results yourself.

Process-tree and nonblocking options

With --subprocesses, record or top can include child Python processes such as multiprocessing jobs or gunicorn workers. That matters for services whose work is distributed across workers, where profiling only the parent would miss substantial activity. The --nonblocking option avoids pausing the target process, but the project warns that sampling errors or incomplete stack frames can result, so it trades fidelity for less interruption.

Pricing

There is no paid tier, trial period, seat charge, or usage quota. The free plan includes CPU and thread profiling for Python, C, C++, and Cython, with desktop deployment. It is a strong fit for individuals, teams, and organizations that can operate a command-line profiler themselves. Buyers who need a hosted service, retention controls, or vendor-managed observability should compare it with commercial or freemium alternatives instead of expecting those service features from py-spy.

Platforms

py-spy runs on Linux, macOS, and Windows. Installation routes include PyPI, GitHub release binaries, Cargo, Homebrew, Arch AUR, and Alpine packages, giving both conventional developer setups and distribution-managed environments a path to installation.

Attachment permissions are an operational constraint. macOS always requires root, and Linux commonly requires root when attaching to a non-child process. In Docker and Kubernetes, the project says the container needs the SYS_PTRACE capability to read process memory. These requirements can affect production rollout and may rule out use in tightly restricted environments.

Who it's for

Choose py-spy when you need an open-source profiler that can inspect a live CPython process, generate several downstream-friendly formats, and follow child workers. It is especially well suited to engineers diagnosing CPU usage in services where changing application code or restarting the process is impractical.

It is less suitable when you need a hosted dashboard, long-term storage, built-in fleet management, or profiling without elevated process access. Teams operating locked-down containers should verify the required capability before standardizing on it.

Pros and cons

Pros

• Profiles without code changes or restarts: useful for live incidents and production diagnosis.
• Low-overhead external design: Rust and out-of-process sampling reduce intrusion into the target application.
• Multiple output formats: flame graphs, speedscope, raw data, and Chrome traces support different analysis workflows.
• Child-process coverage: multiprocessing and gunicorn workers can be included with one option.
• Broad availability: Linux, macOS, and Windows support plus several installation channels.

Cons

• Permission and container hurdles: root access or SYS_PTRACE may conflict with security policies.
• Nonblocking trade-off: avoiding pauses can produce sampling errors or partial stacks.
• Sampling limits: it identifies statistical hot spots rather than providing exhaustive event-level tracing.
• Security-update scope: only the most recent version receives security updates.

Alternatives

Profiling Software is the broader category to survey when you want to compare profiling tools by approach and deployment model.

• Grafana Cloud Application Observability is the better fit for hosted observability, with a free tier capped at 2,232 host hours and a Pro option priced at $0.03 per month under its stated platform-fee and usage terms.
• Scalene is another free, open-source Python profiler installable with pip or conda, worth considering when you want a different profiler workflow.
• YourKit .NET Profiler suits teams evaluating a paid profiler ecosystem or qualifying for its free-license arrangements.
• Javadoc is the choice for Java documentation generation included with JDK 25, not Python profiling.
• Node.js --prof is appropriate for generating V8 profiler output from Node.js applications.
• Parca offers an Apache 2-licensed open-source profiling platform for teams seeking a broader service-oriented setup.
• Pyroscope fits hosted or platform-based profiling, with a free plan offering 50 GB ingested per month and 14-day retention, plus paid plans.
• Valgrind is a free GPL-licensed option when you accept substantially slower programs and higher memory use.

Verdict

py-spy is a strong recommendation for developers and operators who need free, low-overhead sampling of live Python processes across major desktop platforms. Its external design, child-process support, and flexible exports make it particularly effective for diagnosing CPU and thread behavior without editing application code. Look elsewhere if your priority is hosted observability, persistent service-level dashboards, or an environment where root access and SYS_PTRACE cannot be granted.