Installation

Warning: These docs are built from the devel branch, so they may cover features that are not yet available in the version published on PyPI.

Basic install

Install the latest release from PyPI:

pip install scope-profiler

This pulls in all hard dependencies: numpy, h5py, and tabulate (tomli is also installed on Python 3.10).

Optional extras

scope-profiler ships several optional dependency groups that you can install with the bracket syntax:

Extra	Install command	What it adds
compression	pip install "scope-profiler[compression]"	Compressed HDF5 output via hdf5plugin
fortran	pip install "scope-profiler[fortran]"	Meson and Ninja for the Python/Fortran example build
likwid	pip install "scope-profiler[likwid]"	LIKWID hardware counters via pylikwid
line-profiler	pip install "scope-profiler[line-profiler]"	Line-by-line profiling via line_profiler
mcp	pip install "scope-profiler[mcp]"	The scope-profiler-mcp server (see MCP server for AI coding agents)
mpi	pip install "scope-profiler[mpi]"	MPI support via mpi4py
notebook	pip install "scope-profiler[notebook]"	IPython and the notebook magics
nvtx	pip install "scope-profiler[nvtx]"	NVTX ranges for NVIDIA Nsight profiling
perf-events	pip install "scope-profiler[perf-events]"	Built-in Linux hardware counters
pproc	pip install "scope-profiler[pproc]"	Plotting backends (including PyVis call graphs), pandas DataFrames, JupyterLab, SnakeViz, and TUI plotting
tui	pip install "scope-profiler[tui]"	Text-only interactive browsing; add pproc for its plots
extras	pip install "scope-profiler[extras]"	All broadly installable runtime integrations above except LIKWID
dev	pip install "scope-profiler[dev]"	Development, tests, documentation, and runtime integrations

pproc is the name of an installation extra, not a CLI subcommand. Use scope-profiler plot, scope-profiler inspect, scope-profiler report, or scope-profiler export for post-processing.

The base install and its hard dependencies above are sufficient for recording timings, writing HDF5, and scope-profiler inspect; extras are needed only for the features they name. use_line_profiler=True raises a clear ImportError if the line-profiler extra is not installed, as use_likwid=True does for pylikwid.

Development install

Clone the repository and install in editable mode with all development dependencies:

git clone https://github.com/max-models/scope-profiler.git
cd scope-profiler
pip install -e ".[dev]"

LIKWID (optional)

LIKWID hardware counter support requires the LIKWID library and the pylikwid Python bindings to be installed on the system. See the LIKWID documentation for build instructions.

pip install "scope-profiler[likwid]" installs the pylikwid bindings, but they build against an existing LIKWID installation — install (or module load) LIKWID first.

pylikwid is linked against liblikwid.so, and many cluster modules put likwid-perfctr on PATH without adding the library to LD_LIBRARY_PATH, which makes import pylikwid fail with ImportError: liblikwid.so.5: cannot open shared object file. scope-profiler recovers from this on its own: it locates the library via LIKWID_HOME / LIKWID_ROOT (or the prefix of likwid-perfctr on PATH) and loads it before importing the bindings, so module load likwid is enough.

If LIKWID lives somewhere none of those point to, set the loader path yourself before starting Python:

export LD_LIBRARY_PATH="/path/to/likwid/lib:$LD_LIBRARY_PATH"
python -c "import pylikwid"

Counters are only recorded when the process is started under LIKWID’s marker mode — likwid-perfctr -C 0 -g CLOCK -m python script.py, or likwid-mpirun ... -marker. Run the script plainly and the marker calls become no-ops: the timings are still recorded, there are simply no counters. See LIKWID hardware counters.

Verify installation

>>> from scope_profiler import ProfileManager
>>> ProfileManager.setup()
>>> with ProfileManager.region("test"):
...     pass
>>> ProfileManager.finalize()
profiling_data.h5  (1 rank(s))
  region  ranks  calls  total [s]  avg [s]
  ...