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.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 the filename of saved profile runs using a callback (#393)
• Adds an aiohttp.web example to the documentation (#389)

v5.0.3

2 July 2025

• Fix a bug where the HTML renderer would crash when the profile is empty (#377)

v5.0.2

24 May 2025

• Fix a bug that caused jupyter notebooks to continue to run after a profiled cell was interrupted with Ctrl-C (#373)
• Fix a type annotation issue when using mypy and import pyinstrument (#373)

v5.0.1

23 January 2025

• Adds a Django option to customise the filename of saved profile runs (#339)
• Improve the FastAPI integration docs (#355)
• Include more options in the IPython magic (#350)

v5.0.0

11 October 2024

Loads of improvements to the HTML renderer!

• Timeline mode - see and zoom into an interactive linear timeline!

  - HTML mode now has interactive options, rather than needing to set the upfront. - Streamlined the design of the HTML page header. - HTML Call stack view supports arrow key navigation. - The way ‘library’ code is detected has been changed. Previously, if the string ‘/lib/’ occurred in the file path, that was considered library code (and collapsed by default). Now, pyinstrument captures the paths of the Python install and any active virtualenv/conda env at profile time. Files that are stored there are considered library. That should give fewer false positives. - Calls to profiler.start() can now pass a target_description parameter, which is displayed in the profile readout.

Check my blog post for more info on the new features.

v4.7.3

6 September 2024

• Fix a bug introduced in 4.7.0 which would cause the profiler to crash when profiling code with unusual locals, notably some pytest extensions (#332)
• Fix a bug that causes pyinstrument to fail to import packages like glom on Python 3.12 or later, which mutate the locals() dict. (#336)
• Fix a bug that caused a UnicodeDecodeError on some platforms (#330)
• Fix a DivideByZero error that occurs in some situations
• The IPython integration takes greater step to ensure a clean profile output, by ensuring internal frames are trimmed before printing. (#321)

v4.7.2

5 August 2024

• Add CPython 3.13 wheels
• Fix a bug that caused the HTML output to fail to render in some browser contexts (#328)

v4.7.1

2 August 2024

• Fix issue with PyPI upload

v4.7.0

1 August 2024

• Adds a new, convenient API for profiling chunks of Python code! You can now profile simply using a with block, or a function/method decorator. This will profile the code and print a short readout into the terminal. (#327)
• Adds new, lower overhead timing options. Pyinstrument calls timers on every Python function call, which is fine on systems with fast timing available, but it adds significant overhead on systems that require a syscall for each, such as some Docker environments. Pyinstrument will now detect slow timers present a warning with two choices. You can enable a 'timing thread', which offloads the timing workload from the profiled thread, or, if you're happy with lower resolution, you can opt to use a 'coarse' timer, which is provided on some Linux systems. (#273)
• Alt-click rows in the HTML output to collapse/expand the whole tree (#325)
• Adds a flat argument to the console output, to present a flat list of functions (#294)
• Adds a Litestar example config and docs (#284)
• Preliminary Python 3.13 support (#322)

v4.6.2

26 January 2024

• Fixes a bug with the pstats renderer, where additional frames could be seen in the output. (#287)
• Adds show_all option to Profiler.output_html

v4.6.1

8 November 2023

• Fixes a bug with unwanted variable expansion in the IPython magics %pyinstrument (#278)

v4.6.0

12 October 2023

• Adds a feature -c, which allows profiling code directly from the command line, like python -c. (#271)
• Adds a convenience method Profiler.write_html, for writing HTML output to a file directly. (#266)

v4.5.3

7 September 2023

• Fix a problem in the packaging process that prevented upload to PyPI

v4.5.2

1 September 2023

• Show the program name in the header of the HTML output (#260)
• Improve program name capture through resilience to other programs modifying sys.argv (#258)
• Add support for Python 3.12 (#246)

v4.5.1

22 July 2023

• Fix a bug that caused [X frames hidden] in the output when frames were deleted due to __tracebackhide__ (#255)
• Fix a bug causing built-in code to display the filepath None in the console output (#254)
• Some docs improvements (#251)

v4.5.0

5 June 2023

• Adds a flat mode to the console renderer, which can be enabled by passing -p flat on the command line. This mode shows the heaviest frame as measured by self-time, which can be useful in some codebases. (#240)
• Adds the ability to save pstats files. This is the file format used by cprofile in the stdlib. It's less detailed than pyinstrument profiles, but it's compatible with more tools. (#236)
• Fixes a detail of the --show-all option - pyinstrument will no longer remove Python-internal frames when this option is supplied. (#239)
• Internally to the HTML renderer, it now uses Svelte to render the frontend, meaning profile HTML files bundle less javascript and so are smaller. (#222)

v4.4.0

5 November 2022

• Adds the class name to methods in the console & HTML outputs (#203)
• Fix a bug that caused pyinstrument machinery to appear at the start of a profile (#215)
• Frames that set a __traceback_hide__ local variable will now be removed from the output (#217)
• Jupyter/IPython magic now supports async/await, if you run with a --async_mode=enabled flag. (#212)
• Fix a crash when more than one root frame is captured in a thread - this can happen with gevent.
• A big refactor to the backend, allowing more than just static information to be captured. This currently is just powering the class name feature, but more is to come!

v4.3.0

21 August 2022

• Adds buttons in the HTML output to switch between absolute and proportional (percentage) time.
• Adds a command line flag --interval (seconds, default 0.001) to change the interval that pyinstrument samples a program. This is useful for long-running programs, where increasing the interval reduces the memory overhead.
• Includes wheels for CPython 3.11.

v4.2.0

• Adds a command-line option -p --render-option that allows arbitrary setting of render options. This lets you set options like filter_threshold from the command line, by doing something like pyinstrument -p processor_options.filter_threshold=0.

  Here's the help output for the option: -p RENDER_OPTION, --render-option=RENDER_OPTION options to pass to the renderer, in the format 'flag_name' or 'option_name=option_value'. For example, to set the option 'time', pass '-p time=percent_of_total'. To pass multiple options, use the -p option multiple times. You can set processor options using dot-syntax, like '-p processor_options.filter_threshold=0'. option_value is parsed as a JSON value or a string. - Adds the ability to view times in the console output as percentages, rather than absolute times. Use the ConsoleRenderer option time='percent_of_total', or on the command line, use -p, like pyinstrument -p time=percent_of_total. - Adds command line options for loading and saving pyinstrument sessions. You can save the raw data for a pyinstrument session with -r session, like pyinstrument -r session -o session.pyisession myscript.py. Loading is via --load, e.g. pyinstrument --load session.pyisession. - Command line output format is inferred from the -o output file extension. So if you do pyinstrument -o profile.html myscript.py, you don't need to supply -r html, pyinstrument will automatically use the HTML renderer. Or if you do pyinstrument -o profile.pyisession myscript.py, it will save a raw session object. - Adds usage examples for FastAPI and pytest to the documentation. - Fixes a bug causing NotImplementedError when using async_mode=strict. - Adds support for Python 3.11

v4.1.1

• Fixed an issue causing PYINSTRUMENT_PROFILE_DIR_RENDERER to output the wrong file extension when used with the speedscope renderer.

v4.1.0

• You can now use pyinstrument natively in an IPython notebook! Just use %load_ext pyinstrument at the top of your notebook, and then %%pyinstrument in the cell you want to profile.
• Added support for the speedscope format. This provides a way to view interactive flamecharts using pyinstrument. To use, profile with pyinstrument -r speedscope, and upload to the speedscope web app.
• You can now configure renderers for the Django middleware file output, using the PYINSTRUMENT_PROFILE_DIR_RENDERER option.
• Added wheels for Linux aarch64 (64-bit ARM).

v4.0.4

• Fix a packaging issue where a package called 'test' was installed alongside pyinstrument
• Use more modern C APIs to resolve deprecation warnings on Python 3.10.
• Minor docs fixes

v4.0.3

• CPython 3.10 support
• Improve error messages when trying to use Profiler from multiple threads
• Fix crash when rendering sessions that contain a module in a FrameGroup

v4.0.2

• Fix some packaging issues

v4.0.0

• Async support! Pyinstrument now detects when an async task hits an await, and tracks time spent outside of the async context under this await.

  So, for example, here's a simple script with an async task that does a sleep:

  ```python import asyncio from pyinstrument import Profiler

  async def main(): p = Profiler(async_mode='disabled')

  with p:
      print('Hello ...')
      await asyncio.sleep(1)
      print('... World!')
  
  p.print()
  

  asyncio.run(main()) ```

  Before Pyinstrument 4.0.0, we'd see only time spent in the run loop, like this:

  ``` _ . __/__ _ _ _ _ /_