flox

library0.11.2pypypi✓ verified 87d ago

Flox is a Python library that provides strategies for fast GroupBy reductions with dask.array, significantly enhancing performance for operations like climatologies, resampling, and histogramming. It was formerly known as `dask_groupby` and integrates seamlessly with xarray to offer more performant GroupBy and Resampling operations.

data database workflow

pip install flox

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · FLOX

flox

datapythonv0.11.2

Install

11.6s avg

Import

1538ms

Disk

307MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.10.4 · 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.920 runs

installs and imports cleanly · install 0.0s · import 1.597s · 308.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 11.6s · import 1.480s · 295MB

307MB installed

● package 307MB

Code

Verified usage

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

groupby_reduce

✓ from flox import groupby_reduce

xarray_reduce

✓ from flox.xarray import xarray_reduce

For Xarray objects and lazy grouping by Dask arrays.

This quickstart demonstrates how to use `flox.groupby_reduce` with a Dask array and a NumPy array of group labels to compute the mean for each group. The `expected_groups` argument ensures all groups are present in the output, even if some are empty.

import dask.array as da from flox import groupby_reduce import numpy as np # Create a sample Dask array data = da.random.random((1000, 10), chunks=(100, 10)) # Create a 'by' array for grouping (e.g., categories 0-9) groups = np.random.randint(0, 10, size=1000) # Perform a GroupBy reduction (e.g., mean) result_mean, group_labels = groupby_reduce( data, groups, func="mean", expected_groups=np.arange(10) ) print("Grouped Means (first 5 groups):\n", result_mean.compute()[:5]) print("Group Labels:\n", group_labels)

Debug

Known issues

breakingThe library was previously known as `dask_groupby`. Code relying on the old package name or import paths will break.

fix

Update imports from `dask_groupby` to `flox` and adjust any related API calls.

affects: <0.1.0 (pre-rename)

gotchaWhen `flox` (version >= 2022.06.0) is installed, Xarray will automatically use `flox` by default for its `.groupby`, `.groupby_bins`, and `.resample` operations. This implicit usage can change performance characteristics or expose underlying `flox` issues.

fix

Be aware that Xarray's GroupBy methods might be leveraging `flox`. To debug performance or unexpected behavior, consider isolating `flox` or temporarily uninstalling it to revert to Xarray's default GroupBy engine.

affects: xarray>=2022.06.0 with flox installed

gotchaCustom reductions specified using `Aggregation` instances might not be fully functional or have undefined behavior in certain scenarios.

fix

Rely on the built-in reduction functions (e.g., 'mean', 'sum') first. If custom logic is required, thoroughly test its behavior and consult documentation/issues for known limitations.

affects: All current versions (0.11.2)

gotchaHigh memory usage can occur with `flox` aggregations in Dask, particularly when lower-level tasks (e.g., data loading) continue running while higher-level reduction tasks are uncomputed.

fix

Monitor Dask dashboard for task graph progression. Consider rechunking strategies, explicit method selection (e.g., `method='map-reduce'`), or breaking down computations into smaller steps if memory issues persist.

affects: All current versions (0.11.2)

gotchaFor Dask arrays, `flox` uses heuristics (since v0.9.0) to choose the optimal parallel algorithm (`map-reduce`, `blockwise`, `cohorts`). While generally robust, specific data distributions or chunking patterns might benefit from explicitly setting the `method` parameter in `groupby_reduce` or `xarray_reduce`.

fix

If performance is not as expected, experiment with `method` and `reindex` arguments (e.g., `method='map-reduce'`, `method='blockwise'`, `method='cohorts'`) to find the best strategy for your data.

affects: >=0.9.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'flox'

The 'flox' library is not installed in your Python environment or the environment where you are running your code.

fix

Install the library using pip: `pip install flox` or mamba/conda: `mamba install flox` or `conda install -c conda-forge flox`.

TypeError: any() got an unexpected keyword argument 'skipna'

This error typically arises from an incompatibility when using xarray's groupby with flox for 'any()' or 'all()' reductions, where a 'skipna' argument is passed to flox but not correctly handled by the underlying aggregation function due to version mismatches or specific configurations.

fix

Ensure both xarray and flox are updated to their latest versions. This specific issue was addressed in flox (e.g., in xarray-contrib/flox#339) to handle 'skipna' correctly for these aggregations. If the issue persists, explicitly set `skipna=False` or restructure the aggregation if not required.

ValueError: Please provided bin edges for group variable ... in expected_groups.

When performing binning operations using `flox.xarray.xarray_reduce` or `flox.groupby_reduce` with `isbin=True`, this error indicates that the `expected_groups` argument, which should define the bin edges, was not provided or was incorrectly formatted.

fix

When using `isbin=True`, ensure you pass a sequence of bin edges (e.g., `np.array([0, 10, 20, 30])`) to the `expected_groups` argument.

MemoryError

Flox operations, especially with large or poorly chunked Dask arrays, can lead to high memory usage during groupby reductions due to inefficient task scheduling, large intermediate results, or an unsuitable choice of reduction method.

fix

Adjust Dask array chunking to optimize memory. Experiment with different `method` arguments in `flox.groupby_reduce` or `flox.xarray.xarray_reduce` (e.g., `method='cohorts'` for time series data, `method='map-reduce'`). Setting `reindex=True` can sometimes help by reindexing intermediate blockwise results.

Upgrade

Version history

0.11.2latest on PyPI · released Feb 26, 2026

Audit

Dependencies

daskrequiredCore functionality relies on Dask arrays for parallel computing.

xarrayoptionalProvides enhanced GroupBy and Resampling operations for Xarray objects.

numpy_groupiesrequiredWraps vectorized implementations for nD array reductions.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/xarray-contrib/flox ↗

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

homepagehttps://flox.readthedocs.io ↗

docshttps://flox.readthedocs.io ↗

changeloghttps://github.com/xarray-contrib/flox/releases ↗