cProfile 与 py-spy 实测:8 个会骗人的性能数字,以及 Python 3.15 的迁移点
上周我把一段处理两万行文本的脚本从 165 毫秒压到 96 毫秒,靠的是给三段时间各自掐表。做完之后顺手把同一份代码丢进 cProfile,结果第一热点指向一个我压根没打算优化的函数 —— 因为 cProfile 报出的 tottime 里,有一部分时间并不属于那个函数,而是属于剖析器自己。
这篇是我在 Windows 11 + CPython 3.13.14 上,用 cProfile、pstats 与 py-spy 0.4.3 逐条复核的 8 个读数口径。每一条都能用十几行代码复现,报错原文照抄,命令可以直接粘进终端。最后一段是 Python 3.15 起 profiling 包的迁移点 —— 如果你现在写的剖析脚本还要用三年,那一段比前面七段都重要。
TL;DR:同一份 profile 文件,按 tottime、cumtime、ncalls 三种排序会得到三个互不重叠的「第一热点」,没有任何一个默认视图是真相;cProfile 的额外开销记在调用方的 tottime 上,不记在被调方;多进程里 Top1 通常是 CreateProcess 而不是你的代码;py-spy 默认不采阻塞帧,--idle 的语义是「包含空闲」而不是「忽略空闲」。
先把三个工具的分工摆清楚
| 工具 | 默认给你什么 | 会在哪里骗人 |
|---|---|---|
| cProfile 3.13.14 | 精确调用次数与每次耗时 | 开销记在调用方;子进程零覆盖 |
| pstats 排序视图 | 按你指定的列排序的表格 | 三种排序三个答案;strip_dirs 会合并同名函数 |
| py-spy 0.4.3 | 采样,不改代码、可 attach | 默认剔除阻塞帧;采样数本身会抖 |
官方在 Python 3.15 的 profiling 文档里把这条边界说得更直白:统计采样「开销几乎为零、给的是估计值」,确定性追踪「给你精确调用次数、代价是更高开销」,需要精确次数才用后者。这也是我建议的默认姿势:先用采样找方向,再用追踪验次数。站内 11-04 那篇 ThreadPoolExecutor、asyncio 与队列的四形态对拍 回答的是「并发形态怎么选」,本文回答的是「已经慢了,怎么把慢定位出来」—— 两篇的决策层不重叠。
一、同一份 .prof,三种排序给出三个第一热点
被测代码只有三个函数:一个调用 1 次但单次很重的循环、一个被调用 2 万次的极轻函数、一个只负责串起来的 main。
python -m cProfile -o run.prof app.py
python -c "import pstats; pstats.Stats('run.prof').sort_stats('tottime').print_stats(6)"
python -c "import pstats; pstats.Stats('run.prof').sort_stats('cumtime').print_stats(6)"
python -c "import pstats; pstats.Stats('run.prof').sort_stats('calls').print_stats(6)"
同一份文件,80,005 次调用,三个视图的第一名分别是:
| 排序 | 第一名 | 该行关键数字 |
|---|---|---|
| tottime | heavy_once | 1 次调用,0.161 秒 |
| cumtime | main | 累计 0.199 秒,tottime 仅 0.00003 秒 |
| calls | str.lower | 20,000 次,合计 0.006 秒 |
三个名字,零重叠。tottime 第一的是真热点,cumtime 第一的是「入口函数」(它自己几乎不干活),calls 第一的是「被调用最多次」。你打开哪个视图,就会得出哪个结论。
判读建议:先看 cumtime 找「哪条路径整体贵」,再在同一路径内看 tottime 找「贵在哪一段」,calls 只用来判断「是不是调用次数问题」,不要用它找热点。
二、剖析开销记在调用方,不记在被调方
这是本篇最反直觉的一条。我写了一个只做调度的空壳函数,它自己不干任何活,只是循环调用另一个空函数 30 万次:
def leaf():
return None
def dispatch(n):
for _ in range(n):
leaf()
裸跑 dispatch(300000) 是 0.0204 秒。放进 cProfile 之后,它的 tottime 变成 0.0826 秒,涨了 305%,而真正被调用的 leaf 只从 0.020 秒涨到 0.0296 秒(+48%)。
原因是剖析器每次进出函数都要记一笔,这笔开销发生在「调用点」上,也就是记在调用方的 inline time 里。于是任何「自己不干活、只负责调度」的父函数,在 cProfile 里都会凭空变成第二大热点。你照着它去优化,改不动任何东西。
官方 3.15 文档把同一件事写成了另一句更容易漏掉的话:确定性剖析「对 Python 代码加开销,对 C 层函数不加,所以会让两者的比较失真」。把这两句合起来看就明白了 —— 一段纯 Python 代码被剖析时变慢了,不代表它本来慢。
三、strip_dirs() 会把两个文件的同名函数并成一行
我造了两个不同目录、都叫 util.py 的文件,里面各有一个 run():一个跑 30 万次循环(0.0148 秒),一个跑 90 万次(0.0432 秒)。
不 strip 时是两条记录,路径能区分。调用 .strip_dirs() 之后变成一条:util.py: run,ncalls 显示 2,tottime 显示 0.058 —— 两个数被直接相加。
import pstats
pstats.Stats('c.prof').stats # 两条,路径完整
pstats.Stats('c.prof').strip_dirs().stats # 一条,calls=2,时间相加
三倍差距在合并的瞬间消失了。项目里只要有一个 __init__.py 里同名的小函数被多处 import,你就会看到一行「耗时很大但看不出是谁」的记录。判据:如果某行 ncalls 明显大于你预期,先别信它,去掉 strip_dirs 再读一次。
四、ncalls 写成 57313/1 时,percall 的分母是哪个
递归函数最容易被读错。跑一次 fib(22),pstats 那一行是:
57313/1 0.026 0.000 0.026 0.026 fib.py:3(fib)
57313/1 是「总调用 / 本原调用(primitive)」:递归重入 57,312 次,从外部只进来了 1 次。官方把 primitive 定义为「不是由递归引发的调用」,显示格式就是 总次数/primitive。
坑在于 percall 那一列:tottime 除以 57313 得到的数字落在 0.000 这一档,把 57,312 次「同一层重入」摊平了,读不出任何东西。判断递归函数的成本,看 cumtime 那一列的绝对值,别看 percall。
五、多进程:Top1 是 CreateProcess,你的代码零出现
这段最像事故。一个用 multiprocessing.Pool(2) 跑两段循环的脚本,我在脚本内部包了 cProfile(只包父进程),测出来是这样:
| 指标 | 数值 |
|---|---|
| 墙钟 | 1.4046 秒 |
| profile 总时间 | 1.4044 秒 |
| worker 是否出现 | 否 |
| tottime 第一 | _winapi.CreateProcess,1.010 秒(2 次调用) |
| tottime 第二 | _winapi.WaitForMultipleObjects,0.274 秒 |
时间和墙钟对得上,看起来「全采到了」。但真正的热点 worker 一次都没出现,取而代之的是 CreateProcess 拿走了 1.010 秒 —— 那 1 秒里子进程正在跑你的循环,父进程只是在等。你会得出「进程创建太慢」这个完全错误的结论。
想用命令行包装它更糟:python -m cProfile -o mp.prof script.py 在 Windows 上直接崩,-m 模块 方式同样崩,报错原文见下面的报错一。结论很硬:cProfile 覆盖不到子进程,也没有任何警告。要跨进程看,换 py-spy 的 --subprocesses。
六、py-spy 默认把阻塞时间抹掉,--idle 才是「包含空闲」
我写了一个 30 轮循环的脚本,每轮 60 毫秒纯 CPU 加 20 毫秒 time.sleep,真实比例是 75% / 25%。
用默认参数跑 4 次,合计 896 个采样,wait_io 这一帧只命中 1 次(0.11%),burn 稳定在 73.8% 到 78.7% 之间。
加上 --idle 再跑一次,296 个采样里 burn 191(64.5%)、wait_io 66(22.3%)—— 这才接近真相的 25%。
py-spy record --format raw -o out.txt -- python spytest.py
py-spy record --idle --format raw -o idle.txt -- python spytest.py
py-spy record --subprocesses -o sub.svg -- python poolwork.py
原因在 py-spy 的 README 里写得很清楚:它默认「只保留正在执行代码的线程栈,排除睡眠或空闲的线程」,而 --idle 的作用是关掉这个过滤,把空闲帧也纳进来。也就是说 --idle 不是「忽略空闲」,是「包含空闲」—— 名字和直觉正好相反,这一条我踩了两次。README 同时注明:Windows 上被 IO 阻塞的调用目前还不会被判为空闲。
七、采样数自己就在抖:210 到 244
同一脚本、同一配置连跑 4 次,采样数分别是 231、210、211、244。按 100 Hz 采样、脚本跑约 2.4 秒算,理论值就在 240 上下,实测极差 16%。
这条不是缺陷,是采样法的本性:它给的是统计估计。所以两个函数的占比差在 10% 以内时,不要用采样结果判先后 —— 换 -i 把采样间隔调小、把运行时间拉长,或者回到确定性追踪去数调用次数。
八、Python 3.15 起 profile 要走了,cProfile 变成别名
这部分只依据官方文档与 PEP,本机是 3.13.14,跑不了 3.15 的新包,所以不含实测数字。
| 时点 | 变化 |
|---|---|
| 2026-10-09 | Python 3.15 发布,新增 profiling 包(PEP 799) |
| 3.15 | profiling.tracing(cProfile 迁入,cProfile 保留为别名)、profiling.sampling(采样剖析器 Tachyon) |
| 3.15 | profile 模块弃用,import 即触发 DeprecationWarning |
| 3.16 | profile 的所有用法都告警 |
| 3.17 | profile 从标准库移除 |
官方给的命令行形态是 python -m profiling.sampling run app.py,要火焰图加 --flamegraph,要挂到已在跑的进程上用 attach ,确定性那边是 python -m profiling.tracing app.py。pstats 没有被弃用,采样的 --pstats 输出也兼容它 —— 也就是说你现在写的那套 pstats 判读逻辑,三年后还能用。
顺带说一个文档与实测对不上的地方,免得你被绕进去。PEP 799 的动机段写「cProfile only observes the main thread」,但我在 3.13.14 上实测,主线程 enable 之后启动的子线程、以及 enable 之前就存在并阻塞的线程,其 CPU 函数都被记进了 stats(总时间与墙钟一致)。PEP 本身标注为历史文档,别把它当版本事实。要确认你这台机器属于哪种行为,跑这段就行:
import cProfile, threading
def cpu():
s = 0
for i in range(2_000_000):
s += i
p = cProfile.Profile()
p.enable()
t = threading.Thread(target=cpu)
t.start(); t.join()
p.disable()
p.print_stats('tottime')
输出里出现 cpu 就说明子线程被覆盖,没出现就是没有。
一份可复制的判读流程
- 裸跑三次取中位数,先拿到真实墙钟 —— 剖析后的数字不能当基准。
- 用
py-spy record看形态:是 CPU 密集还是大量阻塞,阻塞多就先加--idle再判断。 - 涉及多进程或进程池,直接上
--subprocesses,不要指望 cProfile。 - 锁定可疑函数后,用 cProfile 数确切调用次数,并同时看 tottime 与 cumtime 两个排序。
- 任一数字与你掐表的结果矛盾,优先信掐表 —— 剖析器给你的是时间归属,不是事实。
四个真实报错与修复
报错一:Can't pickle worker,attribute lookup worker on __main__ failed
现象:用 python -m cProfile -o mp.prof script.py 包任何用了 multiprocessing.Pool 的脚本,Windows 下直接退出,exit code 1。
_pickle.PicklingError: Can't pickle <function worker at 0x000001D234161620>: attribute lookup worker on __main__ failed
原因是 cProfile 的命令行入口用 compile() 加 exec() 执行你的脚本,globals 是一个临时字典,worker 并不在真正的 sys.modules['__main__'] 里;spawn 模式起子进程时要按 __main__.worker 反查,查不到就抛。换成 -m 模块 方式一样失败,我两种都试了。
修复:别用 -m cProfile 包多进程脚本。要么按第五段那样在脚本内部只剖析父进程,要么换成 py-spy record --subprocesses。
报错二:EOF read where object expected
现象:pstats.Stats("app.prof") 一打开就抛 EOFError: EOF read where object expected。
原因是 .prof 文件由 marshal.dump() 写入,0 字节文件里没有任何对象可反序列化。而产生 0 字节文件的路径很常见:Ctrl-C 中断、脚本里调了 os._exit()、异常发生在 dump_stats() 之前。官方 profile 文档有一句正对应的说明:剖析只在被调用的命令正常返回时有效,解释器被终止(例如命令内部调用 sys.exit())就不会有结果输出。
先量一下文件大小,别猜:
python -c "import os; p='app.prof'; print(os.path.getsize(p) if os.path.exists(p) else 'missing')"
写入侧改成 try/finally,保证异常路径也能落盘:
prof = cProfile.Profile()
try:
prof.enable()
main()
finally:
prof.disable()
prof.dump_stats("app.prof")
读取侧再补一层 try 捕获 EOFError,输出「这次没采到数据」,而不是让整个脚本崩掉。
报错三:KeyError: 'c'
现象:pstats.Stats(p).sort_stats("c") 抛 KeyError: 'c';sort_stats(3) 抛 KeyError: 3。
原因:sort_stats 内部是直接下标取表,而它支持的前缀缩写是「唯一前缀」—— c 同时命中 calls、cumtime、cumulative,歧义的前缀会被从缩写表里删掉,于是 KeyError,且没有任何提示。整数兼容只认 -1、0、1、2 四个值(分别是 stdname、calls、time、cumulative),3 不在其中。
修复:写全名,或用枚举。
import pstats
from pstats import SortKey
pstats.Stats('run.prof').sort_stats(SortKey.TOTTIME).print_stats(10)
命令行侧更严:-s 只接受完整键名,-s cum 直接 invalid choice 退出 2,只有 -s time、-s tottime、-s cumtime、-s calls 这类全名可用。有意思的是 -s 的默认值在源码里写的是整数 2(对应 cumulative),所以你什么都不加时是按累计时间排,但你要是手动写 -s 2,就会被判为非法选项。
报错四:Another profiling tool is already active
现象:在一个已经开了 cProfile(或已经被 coverage 之类工具占用 tracer)的进程里再 enable() 一个剖析器,抛 ValueError: Another profiling tool is already active。
原因:解释器同一时刻只允许挂一个 profile 钩子。
修复:只开一层。需要同时看覆盖率和耗时,就分两次跑,或者用 py-spy 从进程外部采样 —— 它不占这个钩子。
常见问题
Q:cProfile 的结果能直接当性能基准吗?
不能。官方明确写剖析器是给程序做执行剖面用的,不是拿来做基准测试的,量基准请用 timeit。剖析时纯 Python 代码会变慢、C 层函数不变,两者比较会失真。
Q:为什么我的 profile 里全是 _winapi. 开头的函数?
说明时间花在系统调用与等待上,而不是你的 Python 代码上。Windows 上 CreateProcess、WaitForMultipleObjects 出现在前几位,基本就是多进程或子进程等待,别去优化它们,去优化子进程里那份代码。
Q:py-spy 的采样数为什么比我算的少?
它只在目标进程真实执行时采到栈,进程启动、解释器初始化、退出阶段都可能漏采;再加上线程被判为空闲时会被剔除。想看全貌就加 --idle,并适当延长目标脚本的运行时间。
Q:3.15 之后我现在的脚本要改吗?
import cProfile 和 pstats 都不用动,cProfile 保留为别名、pstats 未被弃用。真正要改的只有 import profile(纯 Python 那个),它在 3.17 会被移除,替换成 profiling.tracing 即可。
结语
这八条口径里,最省钱的一条其实是第二条:剖析器多出来的开销记在调用方的头上,所以「父函数很贵」这个结论天然不可信。我现在的做法是先掐表拿墙钟,再用 py-spy 判形态,最后才用 cProfile 数次数 —— 三层对不上就以掐表为准。
同一台机器上还有两类「不报错但结果错」的情况,处理思路完全一致:asyncio 取消与超时的六处静默失效 讲等待型代码怎么被吞掉,subprocess 退出码为 0 却拿不到输出 讲子进程边界怎么骗人。三篇合起来,基本覆盖了「程序看起来没问题但结果不对」的排查面。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。