benfred/py-spy

¿Qué es?

Funciones clave

• 01Se conecta a procesos Python en ejecución mediante su PID, sin cambios en el código ni reinicios.
• 02Genera flame graphs en SVG, perfiles de speedscope o datos sin procesar.
• 03Ofrece una vista `top` en vivo de las funciones que más tiempo consumen.
• 04Vuelca la pila de llamadas de todos los hilos, con variables locales opcionales.
• 05Permite filtrar los hilos que tienen el GIL y perfilar extensiones nativas.
• 06Sigue procesos secundarios, como los de multiprocessing o los workers de gunicorn.

Casos de uso

• Encontrar las funciones lentas de un servicio Python en producción sin volver a desplegarlo.
• Diagnosticar un proceso bloqueado volcando las pilas actuales de sus hilos.
• Perfilar un script iniciándolo con py-spy record.
• Analizar los puntos de mayor consumo de CPU en extensiones de Cython o C junto con los frames de Python.

Inicio rápido

1. 1

   Instala el binario precompilado desde PyPI

   pip install py-spy
2. 2

   Perfila un proceso en ejecución y genera un gráfico de llamas

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

   Consulta un resumen en vivo, al estilo de top, de un proceso en ejecución

   py-spy top --pid 12345

Antes de usarlo

• !En Linux, normalmente se necesitan permisos de root para perfilar otro proceso.
• !En OSX siempre se necesitan permisos de root, y System Integrity Protection bloquea el perfilado del /usr/bin/python incluido.
• !El perfilado de extensiones nativas mediante --native solo está disponible en algunas combinaciones de plataforma y arquitectura.

Temas

Preguntas frecuentes

¿Qué es py-spy?

Un profiler de muestreo para programas Python que se conecta a procesos en ejecución sin modificar el código ni reiniciarlos. py-spy permite ver en qué emplea el tiempo un programa Python en ejecución. Muestrea el proceso objetivo desde el exterior, así que no hace falta cambiar el código, añadir imports ni reiniciar el programa. Está escrito en Rust y se ejecuta en un proceso separado del que se está perfilando, por lo que su sobrecarga es lo bastante baja como para usarlo con servicios en producción.

¿py-spy es gratuito? ¿Qué licencia tiene?

py-spy es open source bajo la licencia MIT. Revisa los términos de la licencia antes de usarlo en productos comerciales.

¿py-spy sigue mantenido?

Mantenimiento activo. El último commit de py-spy fue el 4 nov 2026.

¿Para qué puedo usar py-spy?

Encontrar las funciones lentas de un servicio Python en producción sin volver a desplegarlo. Diagnosticar un proceso bloqueado volcando las pilas actuales de sus hilos. Perfilar un script iniciándolo con py-spy record. Analizar los puntos de mayor consumo de CPU en extensiones de Cython o C junto con los frames de Python.

¿Cómo se instala py-spy?

Instala el binario precompilado desde PyPI: pip install py-spy Perfila un proceso en ejecución y genera un gráfico de llamas: py-spy record -o profile.svg --pid 12345 Consulta un resumen en vivo, al estilo de top, de un proceso en ejecución: py-spy top --pid 12345

¿Dónde consigo py-spy?

El código fuente y las instrucciones de instalación están en GitHub: https://github.com/benfred/py-spy