Requirements

Python 3.11 to 3.15 supported.

Installation

1. Install with pip:

   python -m pip install profiling-explorer

Usage

profiling-explorer reads pstats files as generated by Python’s profilers: profiling.tracing (called cProfile on Python < 3.15) and profiling.sampling (new in Python 3.15). To use it, first generate a profile file, for example by running your program under cProfile:

$ python -m cProfile -o example.pstats example.py

(Also runnable as python -m profiling.tracing instead on Python 3.15+.)

Then run profiling-explorer with the generated file:

$ profiling-explorer example.pstats

The report will open in your web browser, and you can explore the profile data with the interactive interface. Features:

• Click the calls, internal ms, cumulative ms, or ms/call column headers to sort by that column. ms/call is the cumulative time divided by the number of calls, useful for finding functions that are slow each time they run, rather than those called many times.

• Use the search box to filter by filename or function name. Separate multiple search terms by spaces to match records that contain all terms.

• Press a keyboard shortcut to focus the search box: /, Control+K, or Command+K. Select some text first, like a filename, to pre-fill the search box with that text.

• Hover by a filename + line number pair to reveal the copy button, which copies the location to your clipboard for faster opening.

• Click a filename + line number pair to open that file at that line in your editor. See Opening files in your editor below.

• Click the callers or callees links on the right of a row to see the callers or callees of that function. The ← back link returns to the main table with your previous search and sort order.

usage: profiling-explorer [-h] [--port PORT] [--dev] FILE

positional arguments:
  FILE         The pstats data file to explore.

options:
  -h, --help   show this help message and exit
  --port PORT  Port for the local web server (default: 8099).
  --dev        Run in development mode (enables server reload and debug mode).