mplhep

library1.3.3pypypi✓ verified 21d ago

mplhep is a Python library providing Matplotlib styles and utility functions tailored for High Energy Physics (HEP) plotting. It simplifies the creation of plots compatible with various LHC experiments (ATLAS, CMS, LHCb, ALICE) and offers tools for 1D and 2D histograms, including comparison plots. The library is actively maintained, with the current version being 1.1.2, and sees regular patch and minor releases.

data ai-ml

pip install mplhep

github ↗package ↗

INSTALL

IMPORT

SIG · MPLHEP

mplhep

datapythonv1.3.3

Install

8.1s avg

Import

2823ms

Disk

200MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 2.898s · 197.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 8.1s · import 2.748s · 189MB

200MB installed

● package 200MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mplhep

✓ import mplhep as hep

matplotlib.pyplot

✓ import matplotlib.pyplot as plt

hep.style.use

✓ hep.style.use("CMS")

✗ import hep.style

Styles are applied via `hep.style.use()` and not typically imported directly.

hep.histplot

✓ hep.histplot(...)

This quickstart demonstrates how to import `mplhep`, apply an experiment-specific style (CMS in this case), plot a 1D histogram using `hep.histplot`, and add an experiment label with luminosity and year information. It uses `numpy` for data generation and `matplotlib.pyplot` for basic plot setup and display.

import matplotlib.pyplot as plt import mplhep as hep import numpy as np # Set the CMS experiment style hep.style.use("CMS") # Generate some dummy data for a histogram data = np.random.normal(loc=5, scale=2, size=1000) bins = np.linspace(0, 10, 20) hist, edges = np.histogram(data, bins=bins) # Create a figure and axes fig, ax = plt.subplots() # Plot the histogram using mplhep's histplot hep.histplot(hist, edges, ax=ax, label="My Data") # Add experiment label (e.g., CMS) hep.cms.label(loc=0, data=True, lumi=20, year=2018, ax=ax) # Add a legend and show the plot ax.legend() ax.set_xlabel("X-axis [GeV]") ax.set_ylabel("Entries") plt.tight_layout() plt.show()

Debug

Known issues

breakingmplhep versions 1.0.0 and later have dropped support for Python 3.8. Attempting to install or run with Python 3.8 will result in errors.

fix

Upgrade your Python environment to version 3.9 or newer. Python 3.8 reached its official End-Of-Life (EOL) in October 2024.

affects: >=1.0.0

deprecatedFor Matplotlib versions 3.6 and later, the `axes.Grouper.join()` method, previously used for sharing axes, is deprecated. Older mplhep versions (prior to v1.0.0.rc8) might have compatibility issues or warnings.

fix

Upgrade mplhep to version `1.0.0.rc8` or newer, which replaces the deprecated method with `ax.sharex()` or `ax.sharey()`. If upgrading is not immediately possible, manually adjust axis sharing using `ax.sharex()` / `ax.sharey()` or `ax.get_shared_x_axes().join()` workaround, although the latter is deprecated.

affects: <1.0.0.rc8

breakingThe `v1.0.0` release (and its release candidates like `v1.0.0.rc4`) included significant API refactors (`refactor!`) and introduced new functionalities, such as comparison plotters. Code written for pre-1.0.0 versions, especially regarding label positioning and comparison plots, may require updates.

fix

Consult the `mplhep` documentation for `v1.0.0` to understand the updated API, particularly for label handling and the new comparison plotting functions.

affects: <1.0.0

gotchaAs of `v1.0.0.rc5`, `mplhep` introduced `mplhep.hist()` as a wrapper designed to match the `matplotlib.pyplot.hist()` API. While `hep.histplot()` remains available, `hep.hist()` provides an alternative for users accustomed to `plt.hist()`'s signature.

fix

Consider migrating to `hep.hist()` for new histogram plotting code if you prefer a `plt.hist()`-like interface, or continue using `hep.histplot()` which is designed for pre-binned histogram data.

affects: <1.0.0.rc5

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'mplhep'

The mplhep library is not installed in your active Python environment.

fix

Install mplhep and its associated data package using pip: `pip install mplhep mplhep-data`

mplhep styles (e.g., ATLAS, CMS, LHCb) appear to render incorrectly or display default fonts.

The `mplhep-data` package, which contains the specific fonts and assets required for correct HEP style rendering, is not installed or accessible.

fix

Ensure `mplhep-data` is installed in your environment: `pip install mplhep-data`

TypeError: errorbar() got multiple values for keyword argument 'linestyle'

This typically occurs when using `mplhep.histplot` with `histtype='errorbar'` and passing `linestyle` directly in `**kwargs`. Matplotlib's `errorbar` function, or `mplhep`'s internal handling, might implicitly set `linestyle` already, leading to a conflict.

fix

Avoid directly passing `linestyle` as a top-level keyword argument to `mplhep.histplot` when `histtype='errorbar'`. Instead, rely on `mplhep`'s default styling or consult the Matplotlib `errorbar` documentation for how to control line styles for its components (e.g., `fmt` or `caplines` properties).

mplhep.histplot displays markers at bin edges instead of a continuous histogram outline, or lines do not go down to zero.

This visual discrepancy can arise if `histtype` is not explicitly set to a continuous style (like `'step'` or `'fill'`) or if the `edges` parameter is incorrectly configured, particularly with older versions or specific data inputs.

fix

Explicitly set `histtype='step'` or `histtype='fill'` in your `mplhep.histplot` call to ensure a continuous histogram outline. For proper rendering, especially if providing raw bin contents and edges, ensure the data is structured correctly and rely on the default `edges=True` behavior, which is usually correct for continuous histograms in recent `mplhep` versions.

Upgrade

Version history

1.3.3latest on PyPI · released Aug 15, 2026

Audit

Dependencies

matplotlibrequiredCore plotting library, mplhep is a wrapper for it.

numpyrequiredFundamental package for numerical operations and array handling, common in data processing for plots.

mplhep-datarequiredSub-package containing fonts for mplhep, automatically installed as a dependency.

Agent activity

4 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/scikit-hep/mplhep ↗

packagehttps://pypi.org/project/mplhep/ ↗