Install & Compatibility
Where this runs
tested against v0.11.3 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.256s · 89.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.272s · 86MB
90MB installed
● package 90MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
aggregate
✓ from numpy_groupies import aggregate
✗ import numpy_groupies.aggregate # or from numpy_groupies.aggregate import aggregate
The recommended pattern is to import `aggregate` directly from the top-level package, which automatically selects the best available implementation (e.g., NumPy or Numba).
This quickstart demonstrates the core `aggregate` function, showing how to group values by an index array and apply common aggregation functions like sum, count, and mean. The `fill_value` parameter sets the value for groups that do not appear in `group_idx`.
import numpy as np
from numpy_groupies import aggregate
# Example data: values 'a' to be grouped by 'group_idx'
group_idx = np.array([3, 0, 0, 1, 0, 3, 5, 5, 0, 4])
a = np.array([13.2, 3.5, 3.5, -8.2, 3.0, 13.4, 99.2, -7.1, 0.0, 53.7])
# Aggregate sum for each group
result_sum = aggregate(group_idx, a, func='sum', fill_value=0)
print(f"Aggregated sum: {result_sum}")
# Expected: [10. -8.2 0. 26.6 53.7 92.1]
# Aggregate count of elements in each group
result_count = aggregate(group_idx, a, func='count', fill_value=0)
print(f"Aggregated count: {result_count}")
# Expected: [4 1 0 2 1 2]
# Aggregate mean of values in each group
result_mean = aggregate(group_idx, a, func='mean', fill_value=0)
print(f"Aggregated mean: {result_mean}")
# Expected: [ 2.5 -8.2 0. 13.35 53.7 46.05]
Debug
Known issues
gotchaFor optimal performance, `numba` should be installed. Without it, `numpy-groupies` will automatically fall back to a slower NumPy-only implementation, potentially leading to unexpected performance degradation.fixInstall `numba`: `pip install numba` alongside `numpy-groupies`.
affects: All versions
breakingUsers upgrading to NumPy 2.0 should verify `numpy-groupies` compatibility. NumPy 2.0 introduces significant breaking changes, including an ABI break, changes to type promotion rules, and API modifications that may affect packages depending on it.fixEnsure `numpy-groupies` is updated to a version explicitly supporting NumPy 2.0 (check release notes) or pin `numpy` to <2.0.0 if compatibility issues arise.
affects: numpy-groupies < 0.11.x with numpy >= 2.0.0
gotchaWhen using the `aggregate` function with multidimensional arrays and the `axis` argument, carefully review the documentation regarding different 'Forms' of inputs and outputs. The behavior, especially concerning output shapes and broadcasting, can be complex and non-obvious.fixConsult the official `numpy-groupies` documentation, particularly the sections describing `aggregate` input 'Forms' and the `axis` parameter, to understand the expected output shape and behavior. Experiment with small examples.
affects: All versions
gotchaThe interaction of `fill_value` and `dtype` parameters in `aggregate` can lead to implicit type coercion. If `dtype=None`, a 'sensible type' is chosen, which might not always align with user expectations, especially when handling `NaN` values or mixed data types.fixExplicitly specify the desired `dtype` for the output array to prevent unexpected type conversions. Test `fill_value` behavior with your data types.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'numpy_groupies'
The 'numpy-groupies' library is not installed in the current Python environment or is not accessible in the Python path.
fixInstall the library using pip: `pip install numpy-groupies`
TypeError: only size-1 arrays can be converted to Python scalars
This error typically occurs when the 'group_idx' input to `aggregate` is a multidimensional array, but the 'size' argument is not explicitly provided as a tuple, preventing the function from correctly inferring the output shape.
fixWhen using a multidimensional 'group_idx', explicitly provide the 'size' argument as a tuple matching the desired output dimensions: `npg.aggregate(group_idx, a, size=(dim1_size, dim2_size))`
TypeError: group_idx must be of integer type
The 'group_idx' array, which defines the groups for aggregation, contains non-integer data types, but `numpy-groupies` requires these indices to be non-negative integers.
fixConvert the 'group_idx' array to an integer data type using `astype(int)` before passing it to the `aggregate` function: `npg.aggregate(group_idx.astype(int), a)`
ValueError: one or more indices in group_idx are too large
One or more values in the 'group_idx' array are greater than or equal to the maximum index implied by the 'size' argument, meaning the specified output size is insufficient for the provided group indices.
fixEnsure that the 'size' argument is set large enough to accommodate all group indices (e.g., `np.max(group_idx) + 1`), or verify that the values in 'group_idx' are within the expected range `[0, size-1]`.
Unexpected performance degradation (no specific error message, but a common 'gotcha')
The `numpy-groupies` library uses different implementations for its `aggregate` function, with the Numba-based version being the most performant. Without Numba installed, it silently falls back to a slower NumPy-only implementation.
fixFor optimal performance, install `numba` alongside `numpy-groupies`: `pip install numba numpy-groupies`
Upgrade
Version history
0.11.3latest on PyPI · released May 22, 2025
Audit
Dependencies
numpyrequiredCore functionality relies heavily on NumPy arrays and operations.
numbaoptionalOptional dependency for significantly improved performance of aggregation functions through JIT compilation.