pyinstrument：Python 性能分析的实用选择

pyinstrument 在 GitHub 上已经拿到 7,919 Star 了。

这是一个 Python 性能分析器，核心思路是用统计采样的方式记录程序运行时的调用栈。每隔固定间隔抓取一次栈快照，通过统计推算出各函数的时间占比，而不是在每次函数调用时都插入计时代码。

1、这工具是干嘛的

Python 开发者做性能分析，最常用的工具是标准库里的 cProfile。cProfile 基于确定性分析，每次函数调用都要记录一次进入和退出的时间。这种方式在分析简单脚本时问题不大，但一旦面对复杂程序，分析器本身就会产生显著开销，导致分析结果偏离真实情况。

pyinstrument 采用了统计采样方案。它每 1 毫秒抓取一次调用栈，抓取频率可以自定义。因为不需要在每次函数调用时做额外工作，对程序运行的影响很小。分析结果是一份调用树，清晰展示每个函数占用的时间比例和调用链路。

2、为什么要用它

cProfile 的输出是一张扁平的函数列表，按调用次数或总耗时排序。对于递归调用或深层嵌套的代码，这种视图很难定位真正的瓶颈。你需要自己把各个函数的时间拼起来，才能看出完整的调用链路。

pyinstrument 输出的是树形结构。你能直接看到时间花在哪个调用链路上，从顶层函数一直追踪到最耗时的叶子节点。它还默认折叠库内部调用，把 urllib、asyncio 这类第三方代码隐藏起来，只展示你自己的业务逻辑，省掉大量无关信息。

异步支持是另一个亮点。从 4.0 版本开始，pyinstrument 能正确处理 async/await 代码。当协程遇到 await 进入等待状态时，它会把等待期间的时间归属到对应的异步任务上，而不是错误地算到事件循环头上。这在分析现代 Python 异步应用时非常关键。

HTML 输出也做了升级。5.0 版本引入了时间线模式，可以交互式地查看程序执行的线性时间轴，支持缩放和导航。调用树视图支持键盘方向键操作，整体界面设计更加简洁。

3、安装和使用

安装一条命令搞定：

pip install pyinstrument

支持 Python 3.8 及以上版本。

命令行用法：

pyinstrument myscript.py

代码里用 with 语句包裹需要分析的代码块：

from pyinstrument import Profiler

with Profiler() as p:
    main()

p.print()

也可以用装饰器：

from pyinstrument import Profiler

@Profiler()
def my_function():
    pass

my_function()

输出格式包括终端文本、HTML、JSON 和 speedscope 火焰图。HTML 渲染器支持多种交互选项，可以在浏览器里直接查看和探索分析结果。

对于 Web 框架，pyinstrument 提供了 Django 中间件和 FastAPI 集成示例。Django 中间件可以自动为每个请求生成性能报告，支持自定义文件名和显示条件。

Jupyter 和 IPython 用户也能直接使用。加载 %load_ext pyinstrument 后，在单元格开头加上 %%pyinstrument 就能分析该单元格的运行情况。

4、适合哪些人用

• 需要优化 Python 程序性能、但觉得 cProfile 输出过于冗杂的开发者
• 使用 Django 或 FastAPI 做 Web 开发、需要分析请求响应时间的人
• 在 Jupyter Notebook 里工作、需要快速定位计算瓶颈的数据科学家
• 编写异步代码、需要看清协程调用链路的开发者

pyinstrument 在易用性和信息密度之间找到了一个不错的平衡。安装完就能用，不需要写配置文件，输出结果直观，学习成本很低。对于日常的性能分析需求，它已经足够好用了。

ument 在易用性和信息密度之间找到了一个不错的平衡。安装完就能用，不需要写配置文件，输出结果直观，学习成本很低。对于日常的性能分析需求，它已经足够好用了。