benfred/py-spy

Что это?

Ключевые возможности

• 01Подключается к работающим Python-процессам по PID без изменения кода и перезапуска.
• 02Сохраняет flame graph в SVG, профили speedscope или данные в raw-формате.
• 03Показывает в реальном времени функции, потребляющие больше всего времени, с помощью `top`.
• 04Выводит стеки вызовов всех потоков, при необходимости — с локальными переменными.
• 05Позволяет отбирать потоки, удерживающие GIL, и профилировать нативные расширения.
• 06Отслеживает дочерние процессы, например процессы multiprocessing или воркеры gunicorn.

Сценарии использования

• Поиск медленных функций в production-сервисе на Python без повторного развёртывания.
• Диагностика зависшего процесса с помощью дампа текущих стеков потоков.
• Профилирование скрипта, запущенного через py-spy record.
• Анализ узких мест по CPU в расширениях на Cython или C вместе с кадрами Python.

Быстрый старт

1. 1

   Установить готовый бинарный файл из PyPI

   pip install py-spy
2. 2

   Профилировать работающий процесс и создать flame graph

   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-программе. Он собирает сэмплы целевого процесса извне, поэтому не нужно менять код, добавлять импорты или перезапускать программу. py-spy написан на Rust и работает в отдельном от профилируемого процесса процессе, поэтому его накладные расходы достаточно низки для использования на production-сервисах.

py-spy можно использовать бесплатно? Какая у него лицензия?

py-spy распространяется с открытым исходным кодом под лицензией MIT. Перед использованием в коммерческих продуктах проверьте условия лицензии.

py-spy всё ещё поддерживается?

Активно поддерживается. Последний коммит в py-spy — 6 нояб. 2026 г..

Для чего можно использовать py-spy?

Поиск медленных функций в production-сервисе на Python без повторного развёртывания. Диагностика зависшего процесса с помощью дампа текущих стеков потоков. Профилирование скрипта, запущенного через py-spy record. Анализ узких мест по CPU в расширениях на Cython или C вместе с кадрами Python.

Как установить py-spy?

Установить готовый бинарный файл из PyPI: pip install py-spy Профилировать работающий процесс и создать flame graph: py-spy record -o profile.svg --pid 12345 Посмотреть сводку работающего процесса в реальном времени в стиле top: py-spy top --pid 12345

Где скачать py-spy?

Исходный код и инструкции по установке — на GitHub: https://github.com/benfred/py-spy