pyinstrument：Python 代码性能分析工具

写 Python 的人大多遇到过性能问题。代码跑得慢，想知道瓶颈在哪，cProfile 的输出又太难读，火焰图工具配置起来又麻烦。pyinstrument 就是来解决这个痛点的。它在 GitHub 上有将近 8000 Star，是一个用统计采样方式分析 Python 程序性能的工具，核心目标就是帮你快速定位代码里最耗时的部分，而不需要复杂的配置和学习成本。

用法很简单，三种模式任选

pyinstrument 的安装就是一行 pip 命令，支持 Python 3.8 及以上版本。

用法上有三种常见模式。第一种是命令行直接跑脚本，pyinstrument script.py 就能看到完整的调用树和耗时分布，适合快速分析一个完整程序的运行情况。第二种是在代码里用 with 语句包裹要分析的区域，或者加一个装饰器在函数上，这种方式适合定位特定模块或函数的性能问题，分析粒度更细。第三种是 Jupyter 环境里的 magic 命令 %%pyinstrument，在 notebook 的 cell 顶部加上这行命令即可，做数据分析时不用跳出 notebook 就能完成性能检查。

v4.7 之后还加了一个更便捷的 API，直接用 with 块或者装饰器就能分析代码并自动打印简短报告，比之前手动调用 output_text 更省事。

输出清晰，多种格式可选

默认的控制台输出是一个树状调用栈，每个节点标注了函数名、文件位置和耗时。顶部还会显示总运行时间、CPU 时间和采样数量。这种层级结构比 cProfile 那种扁平列表直观很多，你能直接看到时间是怎么从顶层函数一步步分配到各个子调用上的。

除了控制台，还支持 HTML、JSON、speedscope 等格式。HTML 报告是交互式的单文件，内嵌了所有数据，传给别人直接打开就能看。在浏览器里可以展开折叠调用树，用 Alt 点击可以批量展开或收起整棵子树，还能切换绝对时间和百分比显示。v5.0 大幅改进了 HTML 渲染器，增加了 timeline 模式，可以按时间线查看程序执行过程，支持用方向键在调用栈间导航，整体设计也更加简洁。

几个实用的设计细节

自动隐藏库代码。 pyinstrument 默认会折叠 Python 标准库和第三方库的调用栈，只聚焦你的业务代码。这个从 v3.0 就有的设计省了大量时间，分析时不会被 Django、Flask 这类框架的内部调用干扰视线。v5.0 还改进了库代码检测逻辑，以前是简单匹配路径里的 “/lib/” 字符串，现在会在采样时记录 Python 安装路径和虚拟环境路径，准确率更高。当然，如果你想看全部调用，传 --show-all 就行。

支持异步分析。 从 v4.0 开始支持 async/await 代码，能在 await 处正确标记时间消耗。以前分析异步代码只能看到事件循环内部的调用，看不到真正的业务逻辑耗时。现在 pyinstrument 能追踪到实际的 async 函数，await 处会显示 “[await]” 标记。写 asyncio、FastAPI、aiohttp 这类项目的人可以准确看到异步调度的实际开销。

框架集成。 提供了 Django 中间件的完整配置方案，加几行设置就能自动记录每个请求的性能分析结果，还能自定义保存路径和文件名，方便定位接口响应慢的原因。FastAPI 和 Litestar 也有官方文档中的使用示例，Web 项目的性能监控基本开箱即用。

低开销的采样机制。 pyinstrument 基于 PyEval_SetProfile 做统计采样，不需要信号机制。这意味着可以在非主线程使用，也不会遇到某些环境下信号导致的 IO 错误。采样间隔还可以自定义，默认是 0.001 秒，对于长时间运行的程序，调大间隔可以降低内存占用。v4.7 还增加了 timing thread 和 coarse timer 选项，在 Docker 这类 gettimeofday 较慢的环境下也能保持较低开销。

实际体验和适用场景

从项目给出的示例来看，pyinstrument 的输出结构清晰，问题定位速度快。tree 视图天然适合理解调用关系，时间从上到下逐级分配，一眼就能看出哪个函数占了大头。对于不熟悉火焰图的人来说，这种文本树更容易看懂。

项目维护状态很活跃，最新版本 v5.1.2 发布于 2026 年 1 月。近两年的更新集中在 HTML 渲染器重构（前端改用 Svelte，打包体积更小）、新 API 增加、Python 新版本支持以及已知 bug 修复。版本迭代频繁说明作者还在持续投入。

如果你在找一款比 cProfile 更易用、比火焰图工具更轻量的 Python profiler，pyinstrument 是个务实的选择。命令行、代码内嵌、Jupyter 三种用法覆盖大部分开发和调试场景，HTML 报告可以直接发给团队里其他人看。核心就干一件事：帮你找到代码里最慢的地方，然后清晰地展示出来。

团队里其他人看。核心就干一件事：帮你找到代码里最慢的地方，然后清晰地展示出来。