Python Developer Tooling Handbook – Performance

How to profile a Python script with py-spy

Tim Hopper — Wed, 15 Apr 2026 08:23:33 -0400

This guide shows how to use py-spy to profile a Python script. py-spy is a sampling profiler that runs in a separate process from the program it profiles, so it needs no import, no decorator, and no restart. The result is a flame graph that shows where CPU time is actually spent.

This guide assumes uv is installed. Follow the uv installation guide first if needed.

Install py-spy

Install py-spy as a standalone tool on PATH:

profiling.sampling: Statistical Profiler in the Standard Library

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

profiling.sampling is the statistical sampling profiler that ships with Python 3.15, developed under the codename Tachyon. It samples the call stacks of a Python process on a timer rather than instrumenting every call, and it can attach to a process that is already running by PID. The CLI is invoked as python -m profiling.sampling, with run and attach as the two profiling entry points, dump for a single stack snapshot, and replay for converting saved binary profiles to other output formats.

py-spy: Sampling Profiler for Python

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

py-spy is a sampling profiler for Python programs. It visualizes where a Python process spends its time without restarting the process or modifying its code. py-spy runs in a separate process from the program it profiles and reads stack information out of the target’s memory, which keeps overhead low enough that the project documents it as safe to use against production workloads.

When to Use py-spy

Use py-spy when a Python process is already running and needs to be profiled in place: a web worker under load, a data-pipeline job mid-run, a stuck process that needs a stack dump, or any CPU-bound script whose profile should not be distorted by per-function tracing overhead. py-spy is a practical default for production CPU profiling because it requires no instrumentation and can be attached and detached at will. For line-by-line attribution inside a known hot function, reach for line_profiler; for memory rather than CPU, reach for memray.

Sampling vs deterministic profilers: which should I use?

Tim Hopper — Thu, 07 May 2026 13:56:14 -0400

Two different designs dominate Python profiling, and they produce two different kinds of lies about your program. A deterministic profiler intercepts every function call, records the entry and exit, and tallies the total. A sampling profiler peeks at the call stack on a timer and counts how often each function shows up. Both give you a list of hot functions, and the list will not always agree.

The difference matters because the choice changes what you can trust about the output.