Install & Compatibility
Where this runs
tested against v2026.2.1 · 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.940 runs
installs and imports cleanly · install 0.0s · import 1.641s · 123.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 6.9s · import 1.548s · 117MB
125MB installed
● package 125MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Array
✓ from dask_awkward import Array
✗ from dask_awkward.core import Array
Import Array directly from the top-level package.
from_parquet
✓ from dask_awkward import from_parquet
✗ import dask_awkward.from_parquet
Commonly used functions like from_parquet are directly available under the top-level namespace.
This quickstart demonstrates creating a Dask-Awkward Array from an in-memory Awkward Array, performing a simple operation (getting the length of a nested list), and then computing the result. For real-world use, `da.from_parquet()` or `da.from_json()` are common entry points.
import dask_awkward as da
import awkward as ak
# Create a small Awkward Array
# This can be replaced by loading from a file, e.g., da.from_parquet()
data = ak.Array([{'x': 1, 'y': [1, 2]}, {'x': 2, 'y': []}, {'x': 3, 'y': [3]}])
# Convert it to a Dask Awkward Array with 2 partitions
dask_array = da.from_awkward(data, npartitions=2)
# Perform a simple operation: get the length of 'y' for each record
lengths = dask_array['y'].layout.lengths
# Compute the result
result = lengths.compute()
print(result)
# Expected output: [2, 0, 1]
Debug
Known issues
breakingPython 3.9 support was dropped with version 2026.2.0, and Python 3.8 support was dropped with version 2025.3.0. Users on older Python versions must upgrade or pin `dask-awkward` to an earlier compatible version.fixUpgrade your Python environment to 3.10 or newer. Alternatively, pin `dask-awkward<2026.2.0` for Python 3.9, or `<2025.3.0` for Python 3.8.
affects: >=2026.2.0 (for Py3.9), >=2025.3.0 (for Py3.8)
breakingDask's internal APIs, such as `DataFrameTreeReduction` (removed) and `Task` specifications (changed), have evolved. This means specific `dask-awkward` versions require compatible `dask` versions. Running `dask-awkward` with an incompatible `dask` version can lead to `AttributeError` or other runtime errors.fixEnsure that your `dask-awkward` and `dask` installations are compatible. Install `dask-awkward` without pinning `dask` to allow `pip` to resolve compatible versions, or consult `dask-awkward`'s documentation for tested `dask` ranges.
affects: All versions, especially around 2024.12.x and 2025.2.x releases of dask-awkward
gotchaUsing a Dask-Awkward Array (a 'tracer' or symbolic representation) in contexts that expect an immediate, concrete Awkward Array value can result in `TracerConversionError` or `RuntimeError: Awkward Array tracer used in a concrete context where a value is required.` This often happens inside user-defined functions or operations that are not explicitly Dask-aware.fixEnsure that operations that require concrete values are performed *after* calling `.compute()` on your Dask-Awkward Array. If writing custom functions, use `dask.array.map_blocks` or `dask.dataframe.map_partitions` with functions designed to operate on individual Awkward Array partitions.
affects: >=2024.9.0
gotchaWhen performing filtering or indexing operations that are expected to return a single scalar value, a Dask-Awkward Array will often return a single-item array instead of a direct scalar value, requiring an extra step to extract the scalar.fixIf a scalar is expected, extract it explicitly, e.g., `my_dask_array.compute().item()` or `my_dask_array.compute()[0]` if you are certain it's a single element.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dask_awkward'
The dask-awkward library has not been installed.
fixRun `pip install dask-awkward` to install the package.
RuntimeError: Awkward Array tracer used in a concrete context where a value is required.
An operation tried to access the concrete data of a Dask-Awkward Array (which is a symbolic representation) before `.compute()` was called.
fixEnsure that `.compute()` is called on the Dask-Awkward Array before attempting to use it in operations that require an immediate, concrete Awkward Array. For custom functions, use Dask's `map_blocks` or similar utilities.
ERROR: Package 'dask-awkward' requires a different Python: 3.9.x not in '>=3.10'
Attempting to install or use a recent version of dask-awkward on an unsupported Python version (e.g., Python 3.9 or older).
fixUpgrade your Python environment to version 3.10 or newer. Alternatively, install an older, compatible version of dask-awkward, e.g., `pip install 'dask-awkward<2026.2.0'` for Python 3.9.
AttributeError: module 'dask.dataframe.core' has no attribute 'DataFrameTreeReduction'
You are using an older `dask-awkward` version with a newer `dask` version where certain internal Dask APIs have been removed or changed.
fixUpgrade `dask-awkward` to its latest version to ensure compatibility with recent `dask` releases. `pip install --upgrade dask-awkward`.
Upgrade
Version history
2026.2.1latest on PyPI · released Feb 24, 2026
Audit
Dependencies
daskrequiredCore dependency for parallel and distributed computing.
awkwardrequiredCore dependency for handling nested, irregular data structures.
numpyrequiredUnderlying array library for numerical operations.
pyarrowoptionalRequired for Parquet file I/O operations.
h5pyoptionalRequired for HDF5 file I/O operations.