scikit-hep /awkward
Manipulate JSON-like data with NumPy-like idioms.
★ 990⑂ 156👁 12⑃ 2,831● 1,372▤ 281
+0
日增长
990
stars
156
forks
12
watchers
2,831
prs
1,372
issues
281
releases
README
!
Awkward Array is a library for nested, variable-sized data, including arbitrary-length lists, records, mixed types, and missing data, using NumPy-like idioms.
Arrays are dynamically typed, but operations on them are compiled and fast. Their behavior coincides with NumPy when array dimensions are regular and generalizes when they're not.
Motivating example
Given an array of lists of objects with x, y fields (with nested lists in the y field),
python
import awkward as ak
array = ak.Array([
[{"x": 1.1, "y": [1]}, {"x": 2.2, "y": [1, 2]}, {"x": 3.3, "y": [1, 2, 3]}],
[],
[{"x": 4.4, "y": [1, 2, 3, 4]}, {"x": 5.5, "y": [1, 2, 3, 4, 5]}]
])
the following slices out the y values, drops the first element from each inner list, and runs NumPy's np.square function on everything that is left:
python
output = np.square(array["y", ..., 1:])
The result is
python
[
[[], [4], [4, 9]],
[],
[[4, 9, 16], [4, 9, 16, 25]]
]
The equivalent using only Python is
python
output = []
for sublist in array:
tmp1 = []
for record in sublist:
tmp2 = []
for number in record["y"][1:]:
tmp2.append(np.square(number))
tmp1.append(tmp2)
output.append(tmp1)
The expression using Awkward Arrays is more concise, using idioms familiar from NumPy, and it also has NumPy-like performance. For a similar problem 10 million times larger than the one above (single-threaded on a 2.2 GHz processor),
the Awkward Array one-liner takes 1.5 seconds to run and uses 2.1 GB of memory,
the equivalent using Python lists and dicts takes 140 seconds to run and uses 22 GB of memory.
Awkward Array is even faster when used in Numba's JIT-compiled functions.
See the Getting started documentation on awkward-array.org for an introduction, including a no-install demo you can try in your web browser.
Getting help
View the documentation on awkward-array.org.
Report bugs, request features, and ask for additional documentation on GitHub Issues.
If you have a "How do I...?" question, start a GitHub Discussion with category "Q&A".
Installation
Awkward Array can be installed from PyPI using pip:
bash
pip install awkward
The awkward package is pure Python, and it will download the awkward-cpp compiled components as a dependency. If there is no awkward-cpp binary package (wheel) for your platform and Python version, pip will attempt to compile it from source (which has additional dependencies, such as a C++ compiler).
Awkward Array is also available on conda-forge:
bash
conda install -c conda-forge awkward
Because of the two packages (awkward-cpp may be updated in GitHub but not on PyPI), pip install through git (pip install git+https://...) will not work. Instead, use the Installation for developers section below.
Installation for developers
Clone this repository _recursively_ to get the header-only C++ dependencies. The repository is a uv workspace, so uv sync (or any uv run Top issues
#3188avro reader crash20 comments · 2024-07-26#492High-level function for selecting collections of different jaggedness; "broadcast-slice"?19 comments · 2020-10-21#1807ak.Array wrongly deduces input type18 comments · 2022-10-18#3560`ak.where` produces different output types and shapes in awkward2 versus awkward1 since PR 316817 comments · 2025-06-27#3143`remove_diagonal` option for `ak.cartesian` and `ak.argcartestian`14 comments · 2024-06-06#3992RegularType is not casted ListType when masking13 comments · 2026-05-04#3590Numba type of `IndexedArray` not recognized from `np.asarray` in a numba-compiled function13 comments · 2025-07-28#3675Mix of eager and virtual arrays causes `from_buffers` to fail12 comments · 2025-10-14
Discussions
#4523Version 2.15.00 comments · 2026-11-12#4434Bumping C++ baseline following Python 3.10 deprecation4 comments · 2026-10-17#4432Drop NumPy 1.x support following end-of-life0 comments · 2026-10-16#4418Drop Python 3.10 support following end-of-life3 comments · 2026-10-09#4360Version 2.14.00 comments · 2026-09-17#4308Version 2.13.00 comments · 2026-08-14#4258Version 2.12.00 comments · 2026-07-28#4211Version 2.11.00 comments · 2026-07-20
Latest release
Version 2.15.0 v2.15.0 2026-11-12What's Changed New features feat: add type annotations to five array operations by @Paramveersingh-S in https://github.com/scikit-hep/awkward/pull/4150 feat: preserve CUDA nonlocal output range semantics by @ianna in https://github.com/scikit-hep/awkward/pull/4464 feat: preserve attrs through Arrow serialization by @ikrommyd in https://github.com/scikit-hep/awkward/pull/4349 feat: Replace numba-cuda with numba-cuda-mlir in CUDA backend by @shwina in https://github.com/scikit-hep/awkward/pull/4358 feat: support form-only mergeability checks by @ianna in https://github.com/scikit-hep/awkwa