benfred/py-spy

これは何？

主な機能

• 01PIDを指定して実行中のPythonプロセスにアタッチでき、コードの変更や再起動は不要です。
• 02Flame GraphのSVG、speedscope形式のプロファイル、またはrawデータを出力します。
• 03時間を最も消費している関数をリアルタイムで確認できる`top`表示を提供します。
• 04必要に応じてローカル変数も含め、全スレッドのコールスタックを出力します。
• 05GILを保持しているスレッドに対象を絞ったり、ネイティブ拡張をプロファイルしたりできます。
• 06multiprocessingや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

   実行中のプロセスのtop風ライブサマリーを表示する

   py-spy top --pid 12345

使う前に知っておきたいこと

• !Linuxで別のプロセスをプロファイリングするには、通常root権限が必要です。
• !OSXでは常にroot権限が必要です。また、System Integrity Protectionにより、組み込みの/usr/bin/pythonのプロファイリングはブロックされます。
• !ネイティブ拡張のプロファイリング（--native）は、一部のプラットフォームとアーキテクチャの組み合わせでのみ利用できます。

トピック

よくある質問

py-spy とは？

コードの変更やプロセスの再起動をせず、実行中のPythonプログラムにアタッチできるサンプリングプロファイラー。 py-spyを使うと、実行中のPythonプログラムがどこで時間を使っているかを確認できます。対象プロセスの外部からサンプリングするため、コードの変更やimportの追加、プログラムの再起動は不要です。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 実行中のプロセスのtop風ライブサマリーを表示する: py-spy top --pid 12345

py-spy はどこで入手できますか？

ソースコードとインストール手順は GitHub にあります：https://github.com/benfred/py-spy