benfred/py-spy

这是什么？

核心功能

• 01通过 PID 附加到正在运行的 Python 进程，无需修改代码或重启。
• 02可将分析结果输出为 SVG 火焰图、speedscope 格式或原始数据。
• 03提供类似 top 的实时视图，展示耗时最多的函数。
• 04打印每个线程的调用栈，可选显示局部变量。
• 05支持只采样持有 GIL 的线程，并可分析原生扩展。
• 06可追踪 multiprocessing、gunicorn 等子进程。

适用场景

• 在不重新部署的情况下，定位生产环境 Python 服务中的慢函数。
• 通过导出线程调用栈，排查卡死的进程。
• 使用 py-spy record 启动脚本并生成性能分析报告。
• 结合 Python 帧分析 Cython 或 C 扩展中的 CPU 热点。

快速上手

1. 1

   从 PyPI 安装预编译二进制文件

   pip install py-spy
2. 2

   分析正在运行的进程并生成火焰图

   py-spy record -o profile.svg --pid 12345
3. 3

   实时查看正在运行进程的热点函数摘要

   py-spy top --pid 12345

使用前须知

• !在 Linux 上附加到其他进程通常需要 root 权限。
• !macOS 始终需要 root 权限，且系统完整性保护会阻止分析自带的 /usr/bin/python。
• !--native 原生扩展分析仅在部分平台和架构组合上可用。

标签

常见问题

py-spy 是什么？

一款 Python 程序采样性能分析器，无需修改代码或重启程序即可附加到运行中的进程。 py-spy 用于查看正在运行的 Python 程序把时间花在了哪里。它从外部对目标进程进行采样，不需要修改代码、添加导入或重启程序。工具使用 Rust 编写，与被分析的程序运行在不同进程中，开销很低，可以用于生产环境的服务。

py-spy 可以免费使用吗？用的什么许可证？

py-spy 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

py-spy 还在维护吗？

活跃维护中。py-spy 最近一次提交是在 2026年11月6日。

py-spy 适合用来做什么？

在不重新部署的情况下，定位生产环境 Python 服务中的慢函数。 通过导出线程调用栈，排查卡死的进程。 使用 py-spy record 启动脚本并生成性能分析报告。 结合 Python 帧分析 Cython 或 C 扩展中的 CPU 热点。

py-spy 怎么安装和运行？

从 PyPI 安装预编译二进制文件: pip install py-spy 分析正在运行的进程并生成火焰图: py-spy record -o profile.svg --pid 12345 实时查看正在运行进程的热点函数摘要: py-spy top --pid 12345

在哪里获取 py-spy？

源代码和安装说明在 GitHub 上：https://github.com/benfred/py-spy