Performance issues can be elusive in Python applications, especially when dealing with large systems or complex I/O operations. Py-Spy is a powerful sampling profiler that allows you to see exactly where your Python code is spending time, without modifying the code or restarting the app.

Why Use Py-Spy?

Unlike traditional profilers, Py-Spy runs as an external process and attaches to your running Python program. It works on Linux, macOS, and Windows, with minimal overhead. It also supports both CPython and PyPy.

Installing Py-Spy

pip install py-spy

Or download a standalone binary from the Py-Spy GitHub Releases page.

Basic Usage

To see a live sampling profile of a running process, find the PID and run:

py-spy top --pid

To generate a flame graph (great for visualizing hot spots):

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

Open the SVG in a browser to explore your app’s performance profile interactively.

Using With Docker

If your Python app runs inside Docker, you can use --pid=host and mount /proc to access the necessary information:

docker run --pid=host -v /proc:/host/proc ...

Then use py-spy --pid --procfs /host/proc from inside the container.

Running Py-Spy From Code

You can also launch your script with profiling enabled:

py-spy record -o out.svg -- python your_script.py

Interpreting Flame Graphs

The flame graph shows stack traces in horizontal bars, where wider bars indicate more time spent in that function. You can hover over blocks to see filenames, line numbers, and function names.

Tips for Effective Profiling

  • Start with py-spy top for an overview of which functions consume time.
  • Use py-spy record to dig deeper into what’s happening at each point in time.
  • Focus on optimizing only the hot paths—usually the top 10% of your stack.

Conclusion

Py-Spy is one of the easiest and most effective ways to profile Python programs in production or development. It works without code changes and delivers clear insights in minutes. If you're looking to find bottlenecks and optimize performance, this tool is a must-have in your Python toolkit.

If this post helped you, consider buying me a coffee: buymeacoffee.com/hexshift