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]
  ...

Installation

Contents