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 built with Sphinx from the .qmd sources.
Install Quarto and Pandoc first,
then create a development environment and run the docs target from the
repository root:
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[docs]"
make -C docs html
This refreshes the generated command output and Markdown sources before
building the HTML site. Open docs/build/html/index.html locally, or
serve that directory with any static-file server. The GitHub Pages
workflow uses the same make -C docs html command.
Development
pip install -e '.[dev]'
pytest
See AGENTS.md for the measured benchmark workflow used when optimizing this project.
1 maintainer
Metadata
1 maintainer
Release files for scope-profiler 0.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| scope_profiler-0.7.1.tar.gz | 548.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| scope_profiler-0.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.2 MB
Release files / scope_profiler-0.7.1.tar.gz
| Download URL | scope_profiler-0.7.1.tar.gz |
|---|---|
| Size | 548.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0efc0b72e300b1a7934ede54874b2f4326d66b555924f0b52b699a6b6ba0c8b1
|
|
BLAKE2b-256 checksum How to use checksums |
337c51807b9a92f4985ca9d10e214029766715a8a8828efe348a4efea4f4bd7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 19, 2026.
Transparency logRelease files / scope_profiler-0.7.1-py3-none-any.whl
| Download URL | scope_profiler-0.7.1-py3-none-any.whl |
|---|---|
| Size | 618.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d942347ac7c2992eb923f08375e783dc3ddef56a9b886cad1f5a1a605279e0ca
|
|
BLAKE2b-256 checksum How to use checksums |
73dc597bb16bd6b09bea7094c331cf444a8ceba6f65a3dd4d520bb92e6d2000c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 19, 2026.
Transparency log
