pyinstrument

What it is and what it does

Pyinstrument is a statistical profiler that periodically samples your Python program's call stack to measure where time is spent. Unlike deterministic profilers that instrument every function call, pyinstrument uses sampling to keep overhead low while still identifying the slowest parts of your code. It supports multiple output formats: a hierarchical text tree view for the terminal, an interactive HTML report with timeline and call-stack navigation, and integration with Jupyter notebooks via a magic command.

The package is designed for developers who need to optimize slow Python code but want a tool that's easy to use and doesn't require extensive instrumentation. It works with modern Python versions (3.8+) and includes integrations for Django, FastAPI, Litestar, and aiohttp. Recent versions added a context-manager and decorator API for profiling specific code blocks, plus lower-overhead timing options for environments like Docker where syscall-based timers are slow.

Use it for:

• Profile a web application request to find which handler or middleware is causing latency.
• Identify the slowest function in a data-processing pipeline before optimizing it.
• Profile a Jupyter notebook cell to understand where computation time is spent during analysis.
• Integrate profiling into a Django or FastAPI application to capture production performance issues.
• Use the decorator API to profile individual functions or methods without modifying surrounding code.
• Export HTML reports to share performance analysis with team members or stakeholders.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Pyinstrument is a statistical call-stack profiler that samples your Python program's execution to identify which functions consume the most time, helping you find and optimize performance bottlenecks.

Yes. Pyinstrument is actively maintained, has no known vulnerabilities, carries a permissive license, and solves a real problem—finding performance bottlenecks—with a low-friction install and intuitive API. The medium install friction is offset by broad platform coverage and the value of its output formats. Recommended for any Python developer doing performance optimization.

Install

pyinstrument on PyPI

pip install pyinstrument

uv add pyinstrument

poetry add pyinstrument

Installing pyinstrument

Before you install

Medium install friction due to compiled wheels for multiple platforms and Python versions (3.10–3.12 covered); active maintenance with a release 16 days ago and 8001 repository stars suggest reliable upkeep.

License in practice

Permissive license (BSD) allows use in commercial and proprietary projects with minimal restrictions.

Quickstart

pip install pyinstrument

from pyinstrument import Profiler

profiler = Profiler()
profiler.start()
# ... code to profile ...
profiler.stop()
print(profiler.output_text())

Requires Python 3.8 or later; profiling inside Docker containers may produce inaccurate results due to slow gettimeofday syscalls.

Verify before relying

• Whether the HTML renderer's interactive timeline and flat-list output modes are stable across all supported Python versions.
• Performance overhead of the timing thread option on systems with slow timers.
• Compatibility with pickle-serialized classes when using the CLI profiler.

Package facts

Evidence: pyinstrument-5.1.3-cp310-cp310-macosx_10_9_universal2.whl; pyinstrument-5.1.3-cp310-cp310-macosx_11_0_arm64.whl; pyinstrument-5.1.3-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; pyinstrument-5.1.3-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; pyinstrument-5.1.3-cp310-cp310-musllinux_1_2_aarch64.whl; pyinstrument-5.1.3-cp310-cp310-musllinux_1_2_x86_64.whl; pyinstrument-5.1.3-cp310-cp310-win32.whl; pyinstrument-5.1.3-cp310-cp310-win_amd64.whl; pyinstrument-5.1.3-cp311-cp311-macosx_10_9_universal2.whl; pyinstrument-5.1.3-cp311-cp311-macosx_11_0_arm64.whl; pyinstrument-5.1.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; pyinstrument-5.1.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; pyinstrument-5.1.3-cp311-cp311-musllinux_1_2_aarch64.whl; pyinstrument-5.1.3-cp311-cp311-musllinux_1_2_x86_64.whl; pyinstrument-5.1.3-cp311-cp311-win32.whl; pyinstrument-5.1.3-cp311-cp311-win_amd64.whl; pyinstrument-5.1.3-cp312-cp312-macosx_10_13_universal2.whl; pyinstrument-5.1.3-cp312-cp312-macosx_11_0_arm64.whl; pyinstrument-5.1.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; pyinstrument-5.1.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Keywords: profiling, profile, profiler, cpu, time, sampling

Tags

More Testing packages