Python Profiling: cProfile, py-spy, and Scalene for Performance

You've written a Python script that works perfectly on your laptop, but in production it crawls. Or maybe your web API responds in milliseconds during testing but takes seconds under load. The culprit isn't always obvious—it could be a hidden loop, an inefficient data structure, or a memory leak. Without data, you're guessing. Profiling gives you hard numbers.

Python offers several profiling tools, each with strengths. The built-in cProfile module provides deterministic profiling—it records every function call and its duration. It's great for development but adds overhead that can distort results. py-spy is a sampling profiler that attaches to a running Python process without modifying code, making it ideal for production debugging. Scalene is a modern profiler that tracks CPU, memory, and GPU usage line by line with minimal overhead, offering a comprehensive view.

In this tutorial, you'll learn how to use each tool, interpret their output, and apply them to real-world scenarios. We'll walk through code examples, a production incident, and debugging guides to turn you into a profiling pro. By the end, you'll know which tool to reach for when your Python code needs a speed boost.

Getting Started with cProfile

cProfile is Python's built-in deterministic profiler. It records every function call, including the number of calls, total time, and cumulative time. Use it when you need detailed call counts and you're profiling in a development or staging environment.

To profile a script, run:

``bash python -m cProfile -o output.prof my_script.py ``

The -o flag saves the profile data to a file. You can then analyze it with the pstats module or visualize with tools like snakeviz.

Let's profile a simple script that simulates a slow computation.

import time

def slow_function():
    total = 0
    for i in range(1000000):
        total += i ** 2
    return total

def main():
    result = slow_function()
    print(f"Result: {result}")

if __name__ == "__main__":
    main()

Analyzing cProfile Output with pstats

The pstats module allows you to sort and filter profile data. After generating a .prof file, you can start an interactive session:

``python import pstats p = pstats.Stats('output.prof') p.sort_stats('cumtime').print_stats(10) ``

This prints the top 10 functions by cumulative time. You can also sort by 'time' (total time spent in the function itself) or 'calls' (number of calls).

Let's analyze the profile from our slow script.

import pstats

p = pstats.Stats('output.prof')
p.sort_stats('cumtime').print_stats(10)

Sampling Profiling with py-spy

py-spy is a sampling profiler that attaches to a running Python process without modifying its code. It takes snapshots of the call stack at regular intervals (e.g., every 10ms). This makes it safe for production use with minimal overhead (typically <1% CPU).

Install py-spy: pip install py-spy

To profile a running script, first get its PID:

``bash py-spy record -o flamegraph.svg --pid 12345 ``

This generates a flame graph SVG that you can open in a browser. You can also use py-spy top for a live top-like view.

Let's simulate a production-like scenario: a Flask app with a slow endpoint.

from flask import Flask
import time

app = Flask(__name__)

@app.route('/slow')
def slow():
    time.sleep(0.5)  # Simulate I/O wait
    total = 0
    for i in range(1000000):
        total += i ** 2
    return str(total)

if __name__ == '__main__':
    app.run()

Interpreting py-spy Flame Graphs

Flame graphs are a visualization of stack traces. Each rectangle represents a function call, with width proportional to the time spent in that function (including its children). The x-axis spans the sample population, and the y-axis shows the call stack depth.

To generate a flame graph with py-spy:

``bash py-spy record -o flame.svg --duration 30 --pid 12345 ``

Open flame.svg in a browser. Look for wide rectangles at the top—they indicate functions where the program spends most of its time. The color is usually random but helps distinguish different stacks.

In our Flask example, you'd see slow (the view function) wide, with time.sleep and the loop inside it. If the loop is the bottleneck, it will appear as a wide rectangle.

py-spy record -o flame.svg --duration 10 --pid $(pgrep -f app.py)

Comprehensive Profiling with Scalene

Scalene is a high-performance CPU, memory, and GPU profiler for Python. It uses sampling and special techniques to achieve low overhead (typically 10-20% slower) while providing line-by-line metrics. It can also detect memory leaks and copy volume.

Install Scalene: pip install scalene

To profile a script:

``bash scalene --html --outfile profile.html my_script.py ``

This generates an HTML report with color-coded lines: red for CPU-intensive, blue for memory-intensive.

Let's profile a script with both CPU and memory issues.

import numpy as np

def compute():
    # Memory-intensive: allocate large array
    data = np.random.rand(10000, 10000)
    # CPU-intensive: perform computation
    result = np.sum(data ** 2)
    return result

if __name__ == '__main__':
    print(compute())

Interpreting Scalene Reports

Scalene's HTML report shows your source code with annotations. Each line has a bar indicating CPU time (red) and memory usage (blue). The width of the bar is proportional to the metric. Hovering over a line shows exact numbers.

For memory, Scalene distinguishes between memory allocated and memory copied. High copy volume often indicates inefficient use of data structures (e.g., copying large lists).

Let's look at a sample report for our memory_cpu_script.

<!DOCTYPE html>
<html>
<head><title>Scalene Report</title></head>
<body>
<!-- Scalene generates an interactive HTML file -->
</body>
</html>

Choosing the Right Profiler

Each profiler has its sweet spot. Here's a quick decision guide:

• cProfile: Use in development when you need exact call counts and detailed function-level timing. Avoid in production due to overhead.
• py-spy: Use in production for live debugging of CPU-bound issues. Minimal overhead, no code changes. Best for flame graphs.
• Scalene: Use during optimization when you need both CPU and memory insights. Ideal for data-intensive applications.

Consider combining them: use py-spy to identify the hot function in production, then use Scalene locally to drill into that function's memory behavior.

Let's see a scenario where we profile a data processing pipeline.

import pandas as pd
import numpy as np

def load_data():
    return pd.DataFrame(np.random.rand(100000, 50))

def process(df):
    # Expensive operation
    return df.apply(lambda x: x ** 2)

if __name__ == '__main__':
    df = load_data()
    result = process(df)
    print(result.shape)

Best Practices for Profiling

To get reliable results, follow these guidelines:

1. Profile realistic workloads: Use data sizes and concurrency levels similar to production.
2. Warm up: Run your code a few times before profiling to avoid including startup overhead.
3. Profile multiple times: Variability is normal; take the median or average.
4. Focus on bottlenecks: Optimize the top 10% of time-consuming functions first.
5. Measure after optimization: Always re-profile to confirm improvement.

Let's implement a simple benchmarking decorator that uses cProfile conditionally.

import cProfile
import functools

def profile(output_file=None):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            profiler = cProfile.Profile()
            profiler.enable()
            result = func(*args, **kwargs)
            profiler.disable()
            if output_file:
                profiler.dump_stats(output_file)
            else:
                profiler.print_stats()
            return result
        return wrapper
    return decorator

@profile(output_file='my_func.prof')
def my_func():
    total = 0
    for i in range(1000000):
        total += i ** 2
    return total

if __name__ == '__main__':
    my_func()