Install & Compatibility
Where this runs
tested against v2026.2.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 132.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.0s · import 0.000s · 122MB
132MB installed
● package 132MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AggHistogram
✓ from dask_histogram import AggHistogram
✗ from dask_histogram import Hist
histogram
✓ from dask_histogram import histogram
histogram2d
✓ from dask_histogram import histogram2d
Demonstrates creating Dask histograms using both a NumPy-like routine and by wrapping a boost-histogram object with a Dask array. Remember to call `.compute()` to get the final histogram object.
import dask.array as da
from dask_histogram.routines import histogram
import boost_histogram as bh
# Create a large Dask array
x = da.random.normal(0, 1, size=(10_000_000,), chunks=1_000_000)
# Method 1: NumPy-like interface
bins = 50
range_min, range_max = -5, 5
dask_hist_numpy_like = histogram(x, bins=bins, range=(range_min, range_max))
print(f"NumPy-like Dask histogram (lazy): {dask_hist_numpy_like}")
computed_hist_numpy_like = dask_hist_numpy_like.compute()
print(f"Computed histogram (NumPy-like): {computed_hist_numpy_like.view()}")
# Method 2: boost-histogram like interface
from dask_histogram import Hist
bh_hist = (bh.Histogram(bh.axis.Regular(bins, range_min, range_max, metadata="x")))
dask_hist_bh_like = Hist.from_boost_histogram(bh_hist, x)
print(f"boost-histogram-like Dask histogram (lazy): {dask_hist_bh_like}")
computed_hist_bh_like = dask_hist_bh_like.compute()
print(f"Computed histogram (boost-histogram-like): {computed_hist_bh_like.view()}")
Debug
Known issues
gotchaDask histograms are lazy computations. They return a Dask object that needs to be explicitly computed using `.compute()` to obtain the final boost-histogram object with actual results. Failing to call `.compute()` will result in working with a Dask graph, not the histogram data itself.fixAlways call `.compute()` on the Dask histogram object to get the final result. Example: `final_histogram = dask_histogram_obj.compute()`
affects: All versions
breakingCompatibility with Dask versions can be sensitive. For instance, `dask-histogram.factory` functionality was broken with `dask>=2024.12.0` and required an update in `dask-histogram==2024.12.0` to fix. Ensure your `dask-histogram` version is compatible with your `dask` version, especially after major Dask releases.fixKeep `dask-histogram` updated to its latest version to ensure compatibility with recent Dask releases. Check release notes for specific Dask version requirements.
affects: Prior to 2024.12.0 when used with dask>=2024.12.0
gotchaWhen using `dask_histogram.Hist.fill()`, the arguments (e.g., `x`, `y`) must be Dask arrays, not raw NumPy arrays or scalar values, unlike `boost-histogram`'s direct `fill()` method. This is a common mistake when migrating from `boost-histogram` to `dask-histogram`.fixEnsure all data intended for filling a `dask_histogram.Hist` object are Dask arrays. Convert NumPy arrays to Dask arrays first (e.g., `da.from_array(my_numpy_array)`).
affects: All versions
gotchaThe internal Dask graph construction for `Hist.fill()` was optimized in version `2024.3.0` to delay the creation of the task graph until `.compute()` is called. This can affect users who were relying on inspecting the Dask graph immediately after calling `fill()` but before `compute()`.fixAdjust any custom graph introspection logic to account for delayed graph creation. The graph is fully formed only after `.compute()` is invoked or a Dask operation that triggers graph building occurs.
affects: >=2024.3.0
Upgrade
Version history
2026.2.0latest on PyPI · released Feb 20, 2026
Audit
Dependencies
daskrequiredCore dependency for parallel computing.
numpyrequiredNumerical computing backend for Dask arrays.
boost-histogramrequiredUnderlying histogramming library providing efficient C++ core.
typing_extensionsrequiredProvides backports of features from Python's typing module.
dask-awkwardoptionalUsed for specific optimizations and features when handling awkward arrays.