How do you profile a script with cProfile and inspect the saved profile using pstats?

### Three ways in, one way out Everything `cProfile` produces is the same object: a stats table that `pstats` reads. What differs is how you start the profiler. **The command line** wraps a whole program without editing it: ```console python -m cProfile -o render.prof render_invoices.py python -m cProfile -s cumtime render_invoices.py python -m cProfile -o render.prof -m mypackage.render ``` `-o` writes the binary profile to a file for later analysis; `-s` skips the file and prints a report sorted by the named key straight to stdout; `-m` profiles a module run as `__main__`, the same way `python -m` normally would. Use `-o` for anything you will look at more than once — the printed report is a one-shot summary, while the `.prof` file can be re-sorted, filtered and merged forever. **`cProfile.run(...)`** profiles a statement given as a string, executed in a fresh `__main__` namespace, and either prints the report or writes it to the filename you pass as the second argument. `cProfile.runctx(...)` is the same with explicit `globals` and `locals` dicts, which is what you need when the statement has to see objects you already built. **`cProfile.Profile`** is the object form, and the one that scales to real code: `enable()` / `disable()` around a region, `runcall(func, *args)` for one call, or — since **Python 3.8** — the `with` statement, because `Profile` supports the context-manager protocol. This is how you profile a slice of a long-lived process rather than a whole script. ```python import cProfile, pstats def render(pages): return sum(len(f"invoice page {p}".encode("utf-8")) for p in range(pages)) with cProfile.Profile() as prof: render(20000) prof.dump_stats("render.prof") pstats.Stats("render.prof").strip_dirs().sort_stats("cumtime").print_stats(5) ``` ### Reading the file back `pstats.Stats` is the reader. Its constructor takes a filename, several filenames, or a live `Profile` object, and an optional `stream=` to send output somewhere other than stdout. The methods you will actually use: * **`strip_dirs()`** — collapses the absolute file paths to bare module names. Purely cosmetic, but a report full of long interpreter paths is unreadable, so it is nearly always the first call. It is irreversible on that `Stats` object; reload the file if you need the paths back. * **`sort_stats(key)`** — orders the rows. `"tottime"` (self time), `"cumtime"` (inclusive time), `"ncalls"` and `"nfl"` (name/file/line) are the ones worth remembering. Multiple keys break ties. * **`print_stats(...)`** — prints the table. With no argument it prints every row, which for a real program is thousands of lines. Pass an integer to cap the row count, a float between 0 and 1 to print that fraction of rows, or a regex string to restrict to matching function names — and you can pass several restrictions, applied in order. * **`print_callers(...)` / `print_callees(...)`** — the caller/callee attribution for the rows that survive the same kind of restriction, which is how you find *who* is driving a hot shared helper. * **`add(*filenames)`** — merges further profiles into this one, summing counts and times. Useful for aggregating several runs or several inputs before you draw conclusions from one sample. * **`dump_stats(filename)`** — writes the (possibly merged) table back out. There is also an interactive browser: `python -m pstats render.prof` opens a small prompt where `sort cumtime`, `stats 20` and `callers <regex>` do the same work without writing a script. It is handy when you are exploring rather than automating. Because the `.prof` file is just a marshalled table, third-party visualizers can render it as a flame-graph or a call graph, and that is often the fastest way to see the shape of a large profile. Nothing about the capture step changes; you still produce the file with `-o` or `dump_stats`. ### The habits that make the output worth reading Profile the **realistic** workload, not a toy one: an invoice renderer profiled over three pages will put its fixed setup at the top of the report and hide the per-page cost that dominates a real run. Profile a **whole** unit of work rather than sprinkling `enable()`/`disable()` around fragments — the overlapping regions are hard to reason about, and you lose the entry-point rows that make `cumtime` useful. Keep the `.prof` files: the interesting comparison is almost always before-and-after, and a saved baseline is what turns "it feels faster" into a number. Finally, remember what the report is measuring. It is CPU-time-shaped, per-call attribution of a single deterministic run, not a benchmark. Use it to decide *what* to optimise; confirm the win with a separate, unprofiled measurement of the same work.