pstats — Statistics for profilers

Source code: Lib/pstats.py

The pstats module provides tools for reading, manipulating, and displaying profiling statistics generated by Python’s profilers. It reads output from both profiling.tracing (deterministic profiler) and profiling.sampling (statistical profiler).

Reading and displaying profile data

The Stats class is the primary interface for working with profile data. It can read statistics from files or directly from a Profile object.

Load statistics from a file and print a basic report:

import pstats

p = pstats.Stats('profile_output.prof')
p.print_stats()

The Stats object provides methods for sorting and filtering the data before printing. For example, to see the ten functions with the highest cumulative time:

from pstats import SortKey

p = pstats.Stats('profile_output.prof')
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

Working with statistics

The Stats class supports method chaining, making it convenient to perform multiple operations:

p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()

The strip_dirs() method removes directory paths from filenames, making the output more compact. The sort_stats() method accepts various keys to control the sort order.

Different sort keys highlight different aspects of performance:

from pstats import SortKey

# Functions that consume the most cumulative time
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

# Functions that consume the most time in their own code
p.sort_stats(SortKey.TIME).print_stats(10)

# Functions sorted by name
p.sort_stats(SortKey.NAME).print_stats()

Filtering output

The print_stats() method accepts restrictions that filter which functions are displayed. Restrictions can be integers (limiting the count), floats between 0 and 1 (selecting a percentage), or strings (matching function names via regular expression).

Print only the top 10%:

p.print_stats(.1)

Print only functions whose names contain “init”:

p.print_stats('init')

Combine restrictions (they apply sequentially):

# Top 10%, then only those containing "init"
p.print_stats(.1, 'init')

# Functions in files matching "foo:", limited to top 50%
p.sort_stats(SortKey.FILENAME).print_stats('foo:', .5)

Analyzing call relationships

The print_callers() method shows which functions called each displayed function:

p.print_callers()

The print_callees() method shows the opposite relationship, listing which functions each displayed function called:

p.print_callees()

Both methods accept the same restriction arguments as print_stats().

Combining multiple profiles

Statistics from multiple profiling runs can be combined into a single Stats object:

# Load multiple files at once
p = pstats.Stats('run1.prof', 'run2.prof', 'run3.prof')

# Or add files incrementally
p = pstats.Stats('run1.prof')
p.add('run2.prof')
p.add('run3.prof')

When files are combined, statistics for identical functions (same file, line, and name) are accumulated, giving an aggregate view across all profiling runs.

The Stats class

class pstats.Stats(*filenames_or_profile, stream=sys.stdout)

Create a statistics object from profile data.

The arguments can be filenames (strings or path-like objects) or Profile objects. If multiple sources are provided, their statistics are combined.

The stream argument specifies where output from print_stats() and related methods is written. It defaults to sys.stdout.

The profile data format is specific to the Python version that created it. There is no compatibility guarantee between Python versions or between different profilers.

strip_dirs()

Remove leading path information from all filenames.

This method modifies the object in place and returns it for method chaining. After stripping, the statistics are considered to be in random order.

If stripping causes two functions to become indistinguishable (same filename, line number, and function name), their statistics are combined into a single entry.

add(*filenames)

Add profiling data from additional files.

The files must have been created by the same profiler type. Statistics for identical functions are accumulated.

dump_stats(filename)

Save the current statistics to a file.

The file is created if it does not exist and overwritten if it does. The saved data can be loaded by creating a new Stats object.

sort_stats(*keys)

Sort the statistics according to the specified criteria.

Each key can be a string or a SortKey enum member. When multiple keys are provided, later keys break ties in earlier keys.

Using SortKey enum members is preferred over strings as it provides better error checking:

from pstats import SortKey
p.sort_stats(SortKey.CUMULATIVE)

Valid sort keys:

String

Enum

Meaning

'calls'

SortKey.CALLS

call count

'cumulative'

SortKey.CUMULATIVE

cumulative time

'cumtime'

N/A

cumulative time

'file'

N/A

file name

'filename'

SortKey.FILENAME

file name

'module'

N/A

file name

'ncalls'

N/A

call count

'pcalls'

SortKey.PCALLS

primitive call count

'line'

SortKey.LINE

line number

'name'

SortKey.NAME

function name

'nfl'

SortKey.NFL

name/file/line

'stdname'

SortKey.STDNAME

standard name

'time'

SortKey.TIME

internal time

'tottime'

N/A

internal time

All sorts on statistics are in descending order (most time consuming first), while name, file, and line number sorts are ascending (alphabetical).

The difference between SortKey.NFL and SortKey.STDNAME is that NFL sorts line numbers numerically while STDNAME sorts them as strings. sort_stats(SortKey.NFL) is equivalent to sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE).

For backward compatibility, the numeric arguments -1, 0, 1, and 2 are also accepted, meaning 'stdname', 'calls', 'time', and 'cumulative' respectively.

Added in version 3.7: The SortKey enum.

reverse_order()

Reverse the current sort order.

By default, the sort direction is chosen appropriately for the sort key (descending for time-based keys, ascending for name-based keys). This method inverts that choice.

print_stats(*restrictions)

Print a report of the profiling statistics.

The output includes a header line summarizing the data, followed by a table of function statistics sorted according to the last sort_stats() call.

Restrictions filter the output. Each restriction is either:

  • An integer: limits output to that many entries

  • A float between 0.0 and 1.0: selects that fraction of entries

  • A string: matches function names via regular expression

Restrictions are applied sequentially. For example:

print_stats(.1, 'foo:')

First limits to the top 10%, then filters to functions matching ‘foo:’.

print_callers(*restrictions)

Print the callers of each function in the statistics.

For each function in the filtered results, shows which functions called it and how often.

With profiling.tracing (or cProfile), each caller line shows three numbers: the number of calls from that caller, and the total and cumulative times for those specific calls.

Accepts the same restriction arguments as print_stats().

print_callees(*restrictions)

Print the functions called by each function in the statistics.

This is the inverse of print_callers(), showing which functions each listed function called.

Accepts the same restriction arguments as print_stats().

get_stats_profile()

Return a StatsProfile object containing the statistics.

The returned object provides programmatic access to the profile data, with function names mapped to FunctionProfile objects containing timing and call count information.

Added in version 3.9.

class pstats.SortKey

An enumeration of valid sort keys for Stats.sort_stats().

CALLS

Sort by call count.

CUMULATIVE

Sort by cumulative time.

FILENAME

Sort by file name.

LINE

Sort by line number.

NAME

Sort by function name.

NFL

Sort by name, then file, then line number (numeric line sort).

PCALLS

Sort by primitive (non-recursive) call count.

STDNAME

Sort by standard name (string-based line sort).

TIME

Sort by internal time (time in function excluding subcalls).

Command-line interface

The pstats module can be invoked as a script to interactively browse profile data:

python -m pstats profile_output.prof

This opens a line-oriented interface (built on cmd) for examining the statistics. Type help at the prompt for available commands.

See also

profiling

Overview of Python profiling tools.

profiling.tracing

Deterministic tracing profiler.

profiling.sampling

Statistical sampling profiler.