scope-profiler

Profile Python code regions—and optionally C, Fortran, MPI, NVTX, and LIKWID—with one consistent API and HDF5 output format.

pip install scope-profiler

Quick start

import scope_profiler as sp

with sp.session():

    @sp.profile("main")
    def main():
        with sp.region("work"):
            sum(range(100))  # replace with the code you want to measure

    main()
# writes profiling_data.h5 and prints a summary

session, region, profile, setup and finalize are the everyday calls, importable from the package root. They are ProfileManager class methods acting on the process-wide default manager, so the two spellings are interchangeable:

from scope_profiler import ProfileManager

with ProfileManager.session():
    with ProfileManager.region("work"):
        ...

For a script that already has regions, the CLI owns the profiling lifecycle:

import scope_profiler as sp


@sp.profile("main")
def main():
    with sp.region("iteration"):
        work()


main()

Run it through Scope Profiler to collect those regions and finalize the output:

scope-profiler run app.py

Running the same file with python app.py leaves profiling disabled and creates no output file. Existing session(), setup(), and finalize() workflows remain available when application code needs direct lifecycle control.

See the quickstart and profiling modes guide for recursive tracing, tags, concurrency, output formats, and advanced APIs.

Profile a pytest suite

The installed package provides an opt-in pytest plugin. It records one region for every selected test, named from its pytest node id, so the normal post-processing commands can show which tests consume the suite’s time:

pytest --scope-profile --scope-profile-out pytest-profile.h5
scope-profiler inspect pytest-profile.h5 --regions-only --sort total
scope-profiler plot durations pytest-profile.h5 -o pytest-plots

By default it measures only each test’s call phase. Include fixture setup and teardown when those are relevant to the investigation:

pytest --scope-profile --scope-profile-phases=all

The plugin uses its own profiling manager, so tests that call ProfileManager.setup() or ProfileManager.finalize() remain isolated. The result measures complete test phases; it does not recursively trace every function pytest calls. Existing application-level Scope Profiler regions are therefore best collected in a dedicated application run when detailed function-level attribution is needed. With pytest-xdist, the plugin cannot yet be used: its workers must not write the same HDF5 file.

See the profiling modes guide for output formats, filtering, concurrency, aggregation, pause/resume, and sampling.

In a notebook

Install the notebook extra and see the notebook magics guide for cell profiling, recursive tracing, comparisons, and exports:

pip install "scope-profiler[notebook]"

Documentation

• Installation
• Quick start
• Python API and post-processing
• CLI reference
• Plotly figures for the web
• Configuration and profiling regions
• MPI, C, and Fortran
• LIKWID, line profiling, and MCP
• Jupyter/IPython magics
• Tutorial notebooks
• Examples

Build the documentation locally

The hosted documentation is an Astro + Starlight site in docs/, set up with the shared starlight-theme. It needs Node 22 or newer, an MPI implementation (mpirun) for the MPI examples, and the docs extra:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
make docs-install
make docs-build

This executes the tutorial notebooks, refreshes the generated command output and builds the site into docs/dist; make docs-dev serves a live preview at http://localhost:4321/scope-profiler/. The GitHub Pages workflow runs the same steps. See the docs page on building the docs for the details.

Development

pip install -e '.[dev]'
pytest

See AGENTS.md for the measured benchmark workflow used when optimizing this project.