Repolode
Submit
joerick

joerick/pyinstrument

A call stack profiler for Python that shows where your code spends its time, with console, HTML and other output formats.

View on GitHubWebsite
Stars
8,026
Forks
302
Open issues
32
Last commit
5 days ago

What is it?

Pyinstrument is a statistical profiler for Python. It samples the call stack while a program runs and then reports which functions account for the most elapsed time, so you can focus optimization effort on the slowest part of your code.

It offers a command-line mode (`pyinstrument script.py`), a Python API with a `with` block or decorator for profiling a specific chunk of code, and renderers for console text, interactive HTML, JSON, pstats and speedscope files. It also supports async code, showing time spent awaiting inside coroutines, and includes integrations for Django middleware, IPython/Jupyter magics, FastAPI and aiohttp examples.

By default it hides frames from library code and highlights your own application code, keeping the output focused on the parts you control.

Key features

  • 01Samples the call stack with low overhead and reports time per function.
  • 02Console, interactive HTML, JSON, pstats and speedscope output formats.
  • 03Async-aware profiling that attributes time spent awaiting to the right call.
  • 04Profile a whole script from the command line or a specific block with a `with` statement or decorator.
  • 05Integrations for Django middleware and IPython/Jupyter magic commands.
  • 06Hides library frames by default so application code stands out.

Use cases

  • Finding the slow function behind a Python script that takes too long to run.
  • Profiling a Django view or middleware to see where request time goes.
  • Diagnosing slow async code where tasks spend time awaiting I/O.
  • Inspecting a notebook cell's performance directly in Jupyter.

Quick start

  1. 1

    Install pyinstrument from PyPI

    pip install pyinstrument
  2. 2

    Profile a script from the command line

    pyinstrument script.py

Things to know

  • The README notes that profiling inside Docker containers can give strange results due to slow timing syscalls.
  • Pickled classes in scripts run with pyinstrument may hit `__main__` serialization errors.

In collections

Concurrency & async libraries

Topics

#python#profiler#performance#debugging#django#async#profile

FAQ

What is pyinstrument?
A call stack profiler for Python that shows where your code spends its time, with console, HTML and other output formats. Pyinstrument is a statistical profiler for Python. It samples the call stack while a program runs and then reports which functions account for the most elapsed time, so you can focus optimization effort on the slowest part of your code.
Is pyinstrument free to use? What license does it have?
pyinstrument is open source under the BSD-3-Clause license. Check the license terms before using it in commercial products.
Is pyinstrument still maintained?
Actively maintained. The last commit to pyinstrument was on Nov 1, 2026.
What can I use pyinstrument for?
Finding the slow function behind a Python script that takes too long to run. Profiling a Django view or middleware to see where request time goes. Diagnosing slow async code where tasks spend time awaiting I/O. Inspecting a notebook cell's performance directly in Jupyter.
How do I install pyinstrument?
Install pyinstrument from PyPI: pip install pyinstrument Profile a script from the command line: pyinstrument script.py
Where can I get pyinstrument?
The source code and installation instructions are on GitHub: https://github.com/joerick/pyinstrument

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects