Pyinstrument is a powerful call stack profiler for Python that helps developers understand why their code is slow. It operates by sampling the call stack at regular intervals, providing a clear, interactive visualization of time spent in different functions. The current stable version is 5.1.2, and the library maintains an active release cadence with frequent updates addressing bugs and introducing new features, particularly around its HTML rendering capabilities.
pip install pyinstrumentVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to profile a section of code using Pyinstrument's `Profiler` class and its `start()`/`stop()` methods, followed by generating both console text output and an interactive HTML report. For profiling an entire script from the command line, you can use `pyinstrument your_script.py`.
Review your profiling reports after upgrading to v5.0.0+ to ensure the 'library' code classification still aligns with your expectations. Adjust custom renderers or filtering if necessary.
For critical performance measurements, compare results with and without the profiler. Use the `--interval` option (e.g., `pyinstrument --interval 0.0001`) to balance overhead and precision. Consider using the `with Profiler():` context manager for profiling only specific, critical sections of code to minimize overall impact.
Always ensure `start()` and `stop()` calls are properly balanced. The `with Profiler() as profiler:` context manager (introduced in v4.7.0) is highly recommended as it automatically handles starting and stopping, even with exceptions, greatly reducing the chance of such errors.
Upgrade to Pyinstrument v4.7.3 or newer to resolve compatibility issues with Python 3.12+ and libraries that modify `locals()` during execution.
Ensure Pyinstrument is installed in the correct virtual environment using `pip install pyinstrument`. If issues persist, verify that the build process for your deployment environment allows C extensions to compile correctly, or consider using a Python version for which pre-built wheels for `pyinstrument_cext` are readily available.
To resolve this, reduce the complexity of the profile by using command-line options like `--hide '*/lib/*'` or `--hide-regex '.*vendor.*'` to exclude irrelevant library code. Alternatively, in the Python API, adjust the `filter_threshold` when rendering the report or consider using alternative renderers such as `speedscope` for better visualization of large profiles.
Decrease the profiling interval to a smaller value to capture samples from very fast code. In the Python API, initialize the profiler with `profiler = Profiler(interval=0.0001)`. When using the command line, use the `--interval 0.0001` option.
Refactor your code to define any classes intended for pickling in a separate Python module and import them into your main script. If possible, ensure that the pickling operation occurs outside the section of code being profiled by Pyinstrument.
No dependency data recorded yet.