+0
Daily
+7
Weekly
+16
Monthly
8,032
stars
303
forks
48
watchers
267
prs
195
issues
15
releases
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 Top issues
#169High memory consumption for long-running tasks9 comments · 2021-12-10#257Better support for sync routes in FastAPI7 comments · 2023-07-22#31Profiling with multiprocessing6 comments · 2017-12-03#352Support multithreaded profiling5 comments · 2024-12-04#340Class names in identifiers in rendered output for aggregated frames corresponding to method calls can be misleading4 comments · 2024-10-02#293Improve the experience with recursive functions4 comments · 2024-02-28#288nevergrad import fails when profiler is active4 comments · 2024-01-18#347Timeline view is difficult to scroll around on3 comments · 2024-10-14
Discussions
#469Would it be possible to publish pre-compiled wheels for Python 3.15?1 comments · 2026-11-11#438Python 3.15: Tachyon1 comments · 2026-04-20#433how to display in more ways?0 comments · 2026-04-01#424Relationship between pyinstrument and Tachyon (profiling.sampling)0 comments · 2026-02-17#399Thanks1 comments · 2025-09-24#378possible to sample python cpp extensions ...?1 comments · 2025-03-25#375Visually inspecting results from a database or easily accessing instrumentation0 comments · 2024-10-07#376Pyinstruments creates long intervals with no profiling0 comments · 2024-10-05
Latest release
v5.1.3 v5.1.3 2026-07-29- 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