`cProfile`

The Python cProfile module provides a deterministic profiler that measures where your program spends time by recording how often and how long functions run. It helps you identify performance bottlenecks by producing profiling statistics that you can print immediately or analyze further with pstats.

Here’s a quick example:

>>> import cProfile

>>> def function():
...     return sum(range(1000))
...

>>> cProfile.run("function()")
         5 function calls in 0.000 seconds
...

Key Features

Profiles Python programs deterministically to measure how often and how long functions run.
Reports per-function call counts and timing statistics (including total and cumulative time).
Saves profiling results to a file for later analysis with pstats.
Supports command-line profiling of scripts or modules, including output and sorting options.
Supports programmatic profiling with cProfile.Profile, including starting and stopping profiling around specific code blocks.

Frequently Used Classes and Functions

Object	Type	Description
`cProfile.Profile`	Class	Collects profiling data and manages profiling sessions.
`cProfile.run()`	Function	Profiles a single statement or function call.
`cProfile.runctx()`	Function	Profiles a statement in a specified global and local context.
`pstats`	Module	Provides tools for reading, manipulating, and printing statistics.
`pstats.Stats`	Class	Reads and formats profiling statistics from files or Profile objects.

Examples

Use the cProfile.Profile class to profile a block of code:

>>> import cProfile

>>> def function():
...     return sum(range(1000))
...
>>> profiler = cProfile.Profile()
>>> profiler.enable()
>>> function()
>>> profiler.disable()
>>> profiler.print_stats()
        26 function calls in 0.000 seconds
...

Common Use Cases

The most common tasks for cProfile include:

Identifying hot paths and slow functions in Python applications.
Profiling a script or module from the command line to reproduce performance issues.
Saving profile output to a file and sorting or filtering it with pstats to find top offenders.
Comparing profiles before and after optimizations to validate improvements.
Combining results from multiple profiling runs with pstats to get an aggregate view.

Real-World Example

To profile a Python function and analyze its performance, you can use cProfile to generate a detailed report. Here’s how to profile a recursive Fibonacci function:

>>> import cProfile

>>> def fibonacci(n):
...     if n <= 1:
...         return n
...     else:
...         return fibonacci(n-1) + fibonacci(n-2)
...

>>> profiler = cProfile.Profile()
>>> profiler.enable()
>>> _ = fibonacci(10)
>>> profiler.disable()
>>> profiler.print_stats()
        202 function calls (26 primitive calls) in 0.000 seconds
...

This example demonstrates using cProfile to analyze the performance of the fibonacci() function, allowing you to identify inefficiencies and optimize your code accordingly.

Tutorial

Profiling in Python: How to Find Performance Bottlenecks

In this tutorial, you'll learn how to profile your Python programs using numerous tools available in the standard library, third-party libraries, as well as a powerful tool foreign to Python. Along the way, you'll learn what profiling is and cover a few related concepts.

intermediate tools

For additional information on related topics, take a look at the following resources: