README

pyinstrument
============





Documentation





Pyinstrument is a Python profiler. A profiler is a tool to help you optimize
your code - make it faster. To get the biggest speed increase you should
focus on the slowest part of your program.
Pyinstrument helps you find it!

 ☕️ Not sure where to start? Check out this video tutorial from calmcode.io!



Installation
------------



    pip install pyinstrument

Pyinstrument supports Python 3.8+.



 To run Pyinstrument from a git checkout, there's a build step.
Take a look at Contributing for more info.

Documentation
-------------

To learn how to use pyinstrument, or to check the reference, head to the
documentation.

Known issues
------------

- Profiling code inside a Docker container can cause some strange results,
  because the gettimeofday syscall that pyinstrument uses is slow in that
  environment. See 83
- When using pyinstrument script.py where script.py contains a class
  serialized with pickle, you might encounter errors because the
  serialisation machinery doesn't know where __main__ is. See this issue
  for workarounds

Changelog
---------

 v5.1.3

_29 July 2026_

-    Fixed Django middleware so PYINSTRUMENT_SHOW_CALLBACK is respected when PYINSTRUMENT_PROFILE_DIR is configured, allowing profiles to be selectively written to disk (452).
-    Fixed Jupyter’s %%pyinstrument magic so console-specific render options—including time=percent_of_total, flat, short_mode, color, and Unicode settings—are correctly applied to text output (446).
-    Fixed long program and command names overflowing the header in HTML reports. Long names now wrap cleanly (449).
-    Added context-manager type annotations so type checkers correctly infer profile as a Profiler in with Profiler() as profile: blocks (445).
-    Expanded wheel-building coverage to include CPython prereleases and GraalPy (442).
-    Replaced the deprecated vendored appdirs implementation with simpler internal platform-specific user-data-directory handling (451).
-    Updated build tooling and dependencies, including cibuildwheel and GitHub Actions.

 v5.1.2

_4 January 2026_

-   Adds the ability to customize description using CLI option --target-description (408)
-   You can set the interval for the Django middleware using the PYINSTRUMENT_INTERVAL option (416)
-   HTMLRenderer can now run preprocessors on the input, to manipulate the call tree before writing to HTML (403)
-   Fix a bug where mismatched start/stops can produce "call stack without an active session" errors (406)
-   Limit sample count for the HTML renderer to ensure the browser can load the sample (407)

 v5.1.1

_12 August 2025_

-   Fix some memory leaks in the low-level C extension (394)

 v5.1.0

_10 August 2025_

-   Precision of printed durations now adapts to the interval of the profile. This allows you to see more detail when the interval, and hides unnecessary detail when the interval is large. (390)
-   Adds an option to the Django middleware to customise