Install & Compatibility
Where this runs
tested against v2.13.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.95 runs
installs and imports cleanly · install 0.0s · import 1.214s · 107.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.0s · import 1.176s · 100MB
106MB installed
● package 106MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This example demonstrates creating an Awkward Array from a nested Python list of dictionaries and then performing a NumPy-like vectorized operation to slice and transform the data.
import awkward as ak
import numpy as np
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]}]
])
# Slice out the y values, drop the first element from each inner list, and square them
output = np.square(array["y", ..., 1:])
print(output)
Debug
Known issues
breakingAwkward Array v2.9.0 and later drops support for Python 3.9. Users on Python 3.9 must upgrade their Python version to 3.10 or newer.fixUpgrade Python to version 3.10 or later.
affects: >=2.9.0
breakingVersion 2.x represents a major rewrite from Awkward Array 1.x. Users migrating from 1.x will encounter significant API changes and should consult the official migration guide.fixRefer to the Awkward Array documentation for the migration guide from v1.x to v2.x.
affects: >=2.0.0
deprecatedThe JAX backend for Awkward Array is deprecated and will be removed in a future release. Users relying on JAX integration should plan to migrate their code.fixReview JAX integration in your code and prepare for its removal. Consider alternative autodifferentiation methods or backends if applicable.
affects: All v2.x versions
gotchaIf pre-compiled binary wheels for `awkward-cpp` (a core dependency) are not available for your specific platform and Python version, `pip` will attempt to compile it from source. This requires a C++ compiler and associated development tools to be installed on your system.fixEnsure you have a compatible C++ compiler (e.g., GCC, Clang, MSVC) and development tools installed, or use a `conda` environment where `awkward-cpp` binaries are typically available.
affects: All versions
gotchaThe Awkward Array JAX backend does not support JIT compilation (via `jax.jit`) on reducers (e.g., `ak.sum`). This is due to limitations in JAX's XLA model, which requires array sizes to not be data-dependent at compile-time.fixAvoid `jax.jit` with Awkward Array reducers when using the JAX backend. Operations outside of JIT compilation or non-reducer operations may still work.
affects: All v2.x versions with JAX backend
gotchaWhile Awkward Array includes fixes for compatibility with specific NumPy 2.x versions (e.g., 2.3), general breaking changes introduced in NumPy 2.0 (such as data type promotion rules and changes to the `copy` keyword behavior) can still affect user code that directly interacts with NumPy or expects specific type behaviors. Users should review the NumPy 2.0 migration guide.fixConsult the NumPy 2.0 migration guide and test your code thoroughly when upgrading NumPy. Explicitly cast data types or adjust `copy` arguments where necessary.
affects: All v2.x versions interacting with NumPy >= 2.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'awkward'
This error occurs when the Awkward Array library is not installed in the Python environment.
fixInstall the Awkward Array library using pip: `pip install awkward`.
AttributeError: module 'awkward' has no attribute 'util'
This error arises due to changes in the Awkward Array library where certain modules have been refactored or removed in newer versions.
fixUpdate the code to use the current API of Awkward Array, referring to the latest documentation for guidance.
AttributeError: module 'awkward' has no attribute 'load'
This error occurs because the 'load' function has been removed or renamed in recent versions of the Awkward Array library.
fixReplace 'awkward.load' with the appropriate function from the updated API, such as 'ak.from_parquet' or 'ak.from_json', based on the data format.
AttributeError: module 'numba' has no attribute 'bool'
This error is due to a bug in the Awkward Array library when using Numba with boolean values.
fixEnsure that both Awkward Array and Numba are updated to their latest versions where this issue has been addressed.
AttributeError: 'Array' object has no attribute 'tolist'
You are attempting to use the `tolist()` method, which is a NumPy `ndarray` method, directly on an `awkward.Array` object. Awkward Array provides its own function for converting to a nested Python list.
fixUse the `ak.to_list()` function to convert an Awkward Array to a nested Python list: `my_python_list = ak.to_list(my_awkward_array)`.
Upgrade
Version history
2.13.0latest on PyPI · released Aug 14, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
numpyrequiredCore dependency for numerical operations and array-like behavior.
awkward-cpprequiredCompiled C++ components for performance, installed as a dependency.
pyarrowoptionalRequired for reading/writing Parquet files.