hist

library2.11.0pypypi✓ verified 23d ago

Hist is an analyst-friendly front-end for boost-histogram, providing enhanced classes and utilities for histogramming in Python. It offers features like named axes, quick construction shortcuts, and integrated plotting capabilities, building on the performance of boost-histogram. The library is actively maintained, with its current version being 2.10.1, and typically releases updates to align with Python and boost-histogram version changes.

data ai-ml serialization

pip install hist

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · HIST

hist

datapythonv2.11.0

Install

13.1s avg

Import

857ms

Disk

363MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.11.0 · 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.910 runs

installs and imports cleanly · install 0.0s · import 0.881s · 647MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 13.1s · import 0.833s · 94MB

363MB installed

● package 363MB

Code

Verified usage

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

Hist

✓ from hist import Hist

✗ import hist.Hist

While 'import hist' is valid, the primary histogram class is 'Hist' and typically imported directly.

Hist.new

✓ from hist import Hist; h = Hist.new.Reg(10, 0, 1, name='x')

Quick construction method for creating histograms without explicit axis imports.

This quickstart demonstrates how to create a simple 1D histogram using Hist's `Hist.new` quick construction, fill it with NumPy array data, and print its representation. The example also shows how to define named and labeled axes. Plotting functionality is available with the `[plot]` extra.

from hist import Hist import numpy as np # Create a histogram with one regular axis h = (Hist.new .Reg(10, 0, 10, name="x", label="X-axis [units]") .Double() # Storage type ) # Fill the histogram with some data data = np.random.normal(5, 1, 1000) h.fill(x=data) # Access counts and plot (requires matplotlib, optional install) # import matplotlib.pyplot as plt # h.plot() # plt.show() print(h)

Debug

Known issues

breakingSupport for older Python versions is periodically dropped. As of v2.10.0, Python 3.9 is no longer supported. v2.9.0 dropped Python 3.8, and v2.8.0 dropped Python 3.7. The library requires Python 3.10+.

fix

Ensure your environment uses Python 3.10 or newer. Upgrade your Python version if necessary.

affects: >=2.8.0

breakingThe minimum required version of `boost-histogram` has increased. For example, v2.10.0 dropped support for `boost-histogram` 1.5, requiring 1.7.0 or later. Earlier versions also saw similar increases.

fix

Upgrade `boost-histogram` to the latest compatible version (e.g., `pip install --upgrade boost-histogram`). Consult `hist` release notes for specific version requirements.

affects: >=2.8.0

deprecatedThe `[plot]` extra was split, with some functionalities moving to a new `[fit]` extra. If you previously installed with `[plot]` and relied on fitting tools, you might need to adjust your installation.

fix

Install with `pip install "hist[plot,fit]"` to ensure all previously available features are present.

affects: <2.7.1

gotchaWhen working with Dask-backed histograms (e.g., `hist.dask.Hist`), the histogram object represents a computation graph. The actual histogram data is only materialized when `.compute()` is explicitly called on the object or a dask `compute()` function is used.

fix

Always remember to call `.compute()` on Dask-backed `hist` objects to get the final in-memory histogram for inspection, plotting, or further non-Dask operations.

affects: All

gotchaUsing named axes is highly recommended as it enables more powerful indexing and manipulation shortcuts. While unnamed axes are allowed, many advanced features and syntactic sugars are designed around named axes. The `NamedHist` class forces names to be used in most places.

fix

When creating histograms, always provide a `name` argument for each axis (e.g., `Hist.new.Reg(..., name='my_axis')`). Consider using `from hist import NamedHist` for stricter enforcement.

affects: All

gotchaIf filling an unweighted storage with weights, `hist.variances()` will return `None` as variances cannot be correctly computed. This can lead to unexpected behavior if you rely on variance calculations.

fix

If you intend to use weighted fills and need variance calculations, ensure you initialize your histogram with a weighted storage type (e.g., `hist.storage.Weight()`).

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hist'

The 'hist' library is not installed in your Python environment or is not accessible from the interpreter you are using.

fix

Install the library using pip: `pip install hist` or `python3 -m pip install "hist[plot,fit]"` to include plotting and fitting capabilities.

AttributeError: module 'hist' has no attribute 'Hist'

This occurs when you've imported the `hist` package using `import hist` but are trying to access the main `Hist` class as `hist.Hist()`, which is not how it's typically exposed or intended for direct access in the module's top level.

fix

Import the `Hist` class directly using `from hist import Hist` and then instantiate it as `Hist(...)`.

ValueError: Duplicated non-empty names are not allowed in the Hist as name is the unique identifier for a Hist object.

You are attempting to create a `Hist` object with two or more axes that share the same `name` attribute. Axis names must be unique to serve as identifiers within a histogram.

fix

Ensure that each axis defined within a single `Hist` object has a unique `name` parameter, for example: `hist.axis.Regular(10, 0, 10, name="x_axis")` and `hist.axis.Regular(10, 0, 10, name="y_axis")`.

TypeError: Regular() missing 3 required positional arguments: 'bins', 'low', and 'high'

The `hist.axis.Regular` constructor requires at least three positional arguments: the number of bins, the lower edge, and the upper edge of the axis, in addition to optional keyword arguments like `name`.

fix

Provide the `bins`, `low`, and `high` values when defining a regular axis, e.g., `h = Hist.new.Reg(50, -5, 5, name="my_axis").Double()` or `hist.axis.Regular(50, -5, 5, name="my_axis")`.

Upgrade

Version history

2.11.0latest on PyPI · released Aug 10, 2026

Audit

Dependencies

boost-histogramrequiredCore backend for histogramming operations.

matplotliboptionalRequired for plotting features when installing with `[plot]` extra.

daskoptionalRequired for Dask-backed histogram operations when installing with `[dask]` extra.

mplhepoptionalRecommended for HEP-style plotting integration.

scipyoptionalOptional for certain functionalities, no longer strictly required by default since v2.5.0.

iminuitoptionalOptional for fitting functionalities, no longer strictly required by default since v2.5.0.

Agent activity

9 hits · last 30 days

node

Resources

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

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

homepagehttps://hist.readthedocs.io ↗

docshttps://hist.readthedocs.io/ ↗

changeloghttps://hist.readthedocs.io/en/latest/changelog.html ↗