{"id":5786,"library":"mplhep","title":"Matplotlib styles for HEP","description":"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.","status":"active","version":"1.1.2","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/mplhep","tags":["matplotlib","HEP","physics","plotting","histograms","scikit-hep","ATLAS","CMS","LHCb","ALICE"],"install":[{"cmd":"pip install mplhep","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core plotting library, mplhep is a wrapper for it.","package":"matplotlib"},{"reason":"Fundamental package for numerical operations and array handling, common in data processing for plots.","package":"numpy"},{"reason":"Sub-package containing fonts for mplhep, automatically installed as a dependency.","package":"mplhep-data","optional":false}],"imports":[{"symbol":"mplhep","correct":"import mplhep as hep"},{"symbol":"matplotlib.pyplot","correct":"import matplotlib.pyplot as plt"},{"note":"Styles are applied via `hep.style.use()` and not typically imported directly.","wrong":"import hep.style","symbol":"hep.style.use","correct":"hep.style.use(\"CMS\")"},{"symbol":"hep.histplot","correct":"hep.histplot(...)"}],"quickstart":{"code":"import matplotlib.pyplot as plt\nimport mplhep as hep\nimport numpy as np\n\n# Set the CMS experiment style\nhep.style.use(\"CMS\")\n\n# Generate some dummy data for a histogram\ndata = np.random.normal(loc=5, scale=2, size=1000)\nbins = np.linspace(0, 10, 20)\nhist, edges = np.histogram(data, bins=bins)\n\n# Create a figure and axes\nfig, ax = plt.subplots()\n\n# Plot the histogram using mplhep's histplot\nhep.histplot(hist, edges, ax=ax, label=\"My Data\")\n\n# Add experiment label (e.g., CMS)\nhep.cms.label(loc=0, data=True, lumi=20, year=2018, ax=ax)\n\n# Add a legend and show the plot\nax.legend()\nax.set_xlabel(\"X-axis [GeV]\")\nax.set_ylabel(\"Entries\")\nplt.tight_layout()\nplt.show()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or newer. Python 3.8 reached its official End-Of-Life (EOL) in October 2024.","message":"mplhep 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"For 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.","severity":"deprecated","affected_versions":"<1.0.0.rc8"},{"fix":"Consult the `mplhep` documentation for `v1.0.0` to understand the updated API, particularly for label handling and the new comparison plotting functions.","message":"The `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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":"<1.0.0.rc5"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}