{"id":1652,"library":"pyinstrument","title":"Pyinstrument Profiler","description":"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.","status":"active","version":"5.1.2","language":"en","source_language":"en","source_url":"https://github.com/joerick/pyinstrument","tags":["profiler","performance","debugging","call stack","sampling","diagnostics"],"install":[{"cmd":"pip install pyinstrument","lang":"bash","label":"Install Pyinstrument"}],"dependencies":[],"imports":[{"symbol":"Profiler","correct":"from pyinstrument import Profiler"},{"symbol":"HTMLRenderer","correct":"from pyinstrument.renderers import HTMLRenderer"},{"symbol":"ConsoleRenderer","correct":"from pyinstrument.renderers import ConsoleRenderer"}],"quickstart":{"code":"from pyinstrument import Profiler\nimport time\nimport os\n\ndef my_slow_function():\n    time.sleep(0.05)\n    another_slow_part()\n\ndef another_slow_part():\n    time.sleep(0.02)\n\n# Using the context manager (recommended for specific code blocks)\nprofiler = Profiler()\nprofiler.start()\n\nfor _ in range(5):\n    my_slow_function()\n\nprofiler.stop()\n\n# Output to console\nprint(\"\\n--- Console Output ---\")\nprint(profiler.output_text(unicode=True, color=True))\n\n# Generate HTML report\n# For simplicity, we'll write to a file directly. In a real app,\n# you might return this HTML via a web framework.\nhtml_output = profiler.output_html()\noutput_filename = os.path.join(os.getcwd(), \"pyinstrument_profile.html\")\nwith open(output_filename, \"w\") as f:\n    f.write(html_output)\nprint(f\"\\nHTML report saved to: {output_filename}\")\nprint(\"Open the HTML file in your browser to view the interactive profile.\")","lang":"python","description":"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`."},"warnings":[{"fix":"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.","message":"In Pyinstrument v5.0.0, the mechanism for detecting 'library' code (code not directly part of your application) was changed. This might alter how the profiler categorizes and displays frames, potentially affecting filtering or interpretation of results for users who relied on the previous classification.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"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.","message":"Pyinstrument, like most profilers, introduces some overhead. While it's designed to be low-overhead, profiling very short-lived functions or extremely high-frequency code paths can still show distorted results. The sampling interval (`--interval` CLI option or `Profiler(interval=...)` parameter) can affect both overhead and precision.","severity":"gotcha","affected_versions":"<5.1.0 (improved in 5.1.0)"},{"fix":"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.","message":"Mismatched calls to `profiler.start()` and `profiler.stop()` can lead to 'call stack without an active session' errors or incomplete profiles. This often happens in complex control flows or when exceptions interrupt profiling.","severity":"gotcha","affected_versions":"<5.1.2 (bug fixed in 5.1.2, but good practice remains)"},{"fix":"Upgrade to Pyinstrument v4.7.3 or newer to resolve compatibility issues with Python 3.12+ and libraries that modify `locals()` during execution.","message":"Pyinstrument versions prior to 4.7.3 could crash on Python 3.12 and later when profiling code that mutates the `locals()` dictionary, affecting compatibility with certain libraries (e.g., `glom`).","severity":"breaking","affected_versions":"<4.7.3 on Python 3.12+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}