py-spy：不用改代码的 Python 性能分析工具

15,237 Star 的 py-spy 是一个采样型性能分析器，定位很清晰：分析正在运行的 Python 程序，不需要重启，不需要改任何代码。

日常做 Python 性能调优，最常见的麻烦就是得在代码里插入分析逻辑，或者重新跑程序带上性能分析参数。这对本地开发还好，但对线上服务基本不可行。py-spy 解决的就是这个问题。

核心特点

py-spy 用 Rust 编写，通过读取目标进程的内存来获取调用栈信息，而不是在 Python 进程内运行分析代码。这意味着它的开销很低，也不会改变被分析程序的行为。Linux、macOS、Windows、FreeBSD 都支持，Python 版本覆盖 2.3 到 2.7 以及 3.3 到 3.14。

安装很简单，pip 直接装，或者下预编译二进制。Homebrew、AUR 这些包管理器也都有。

三个实用命令

py-spy 提供三个子命令，覆盖了不同场景：

record：录制性能数据到文件，默认输出 SVG 火焰图，也支持 speedscope 格式和原始数据。用法是传 PID 或者直接跟要执行的 Python 命令。

top：实时查看哪些函数占用最多时间，类似 Unix top 的交互界面，适合快速定位热点。

dump：打印当前所有线程的调用栈，适合排查程序卡死在哪里的场景，加上 --locals 还能看到局部变量。

为什么这个项目值得关注

1. 对生产环境友好

大多数 Python 分析工具都需要在目标进程内执行，会拖慢服务，甚至改变行为。py-spy 从外部读取内存，理论上可以安全地对线上服务进行采样。

2. 支持原生扩展分析

在 Linux 和 Windows 的 x86-64 平台上，加上 --native 参数就能分析 C/C++ 或 Cython 写的扩展模块。这对于依赖大量数值计算库的项目很有用。

3. 细粒度的过滤能力

可以只采样持有 GIL 的线程，可以排除空闲线程，也可以递归分析子进程。这些选项让输出的数据更干净，减少无关信息干扰。

使用注意事项

由于是跨进程读内存，权限问题需要注意。macOS 上必须 root 运行；Linux 上如果是附加已有进程通常也需要 sudo，但用 py-spy 启动新进程则不需要。Docker 和 Kubernetes 环境里需要开启 SYS_PTRACE 能力。

还有一个 --nonblocking 选项可以完全不暂停目标进程，但代价是采样错误率会上升，偶尔会出现不完整的调用栈。

适合谁用

如果你在维护 Python 后端服务，经常遇到性能问题但没法在测试环境复现，py-spy 是个实用的排查工具。它也适合数据分析类的项目，能快速定位是 Python 代码慢还是底层库慢。

总的来说，py-spy 不是一个万能分析器，但在「不侵入生产环境」这个点上做得足够好，值得放在工具箱里。

的来说，py-spy 不是一个万能分析器，但在「不侵入生产环境」这个点上做得足够好，值得放在工具箱里。