---
id: awkward
version: "2.13.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# awkward — Manipulate JSON-like data with NumPy-like idioms.

License: permissive · Maintenance: active · Downloads: 1.4M/mo

## What it is and what it does

Awkward Array is a library for working with nested, variable-sized data—such as lists of records with mixed types, missing values, and arbitrary nesting depth—using NumPy-like syntax and performance. It bridges the gap between NumPy's speed (which assumes regular, rectangular arrays) and Python's flexibility for irregular structures. Operations are dynamically typed but compiled to machine code, so slicing, filtering, and applying functions across nested structures runs orders of magnitude faster than equivalent Python loops.

The library depends on numpy for core array operations, awkward-cpp for compiled kernels, and fsspec for optional file-system abstraction. It's designed for data science, physics, and information analysis workflows where data arrives in hierarchical or JSON-like formats. The package is actively maintained, supports current Python versions (3.10–3.14), and has no known security vulnerabilities.

Use it for:

- Process particle physics event data with nested detector records and variable-length hit lists.
- Transform JSON-like API responses into columnar arrays for fast aggregation and filtering.
- Analyze time-series data with variable-length event sequences per entity without reshaping.
- Perform NumPy-style operations on ragged arrays from scientific simulations or sensor networks.
- Build data pipelines that preserve nested structure while applying vectorized transformations.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Awkward Array provides NumPy-like operations on nested, variable-sized data structures—lists, records, mixed types, and missing values—with compiled performance and dynamic typing.

Yes. Awkward Array is production-stable, actively maintained, has no security issues, and solves a real problem: fast operations on irregular nested data. Install it if your workflow involves JSON-like structures, ragged arrays, or hierarchical data that NumPy alone cannot handle efficiently. The low install friction and permissive license make it a low-risk addition.

## Install

pip install awkward
uv add awkward
poetry add awkward

## Installing awkward

Before you install: Low friction: pure Python package with a precompiled C++ dependency (awkward-cpp) that ships as a wheel for common platforms. Active maintenance with a recent release and no known vulnerabilities.

License in practice: BSD-3-Clause is permissive; you may use, modify, and distribute this package freely in commercial and private projects, provided you include the license notice.

Quickstart:

pip install awkward

import awkward as ak
import numpy as np

array = ak.Array([{"x": 1.1, "y": [1]}, {"x": 2.2, "y": [1, 2]}])
result = np.square(array["y", ..., 1:])

Requires Python 3.10 or later. If awkward-cpp wheels are unavailable for your platform, pip will attempt to build from source, requiring a C++ compiler.

Verify before relying:

- Whether fsspec integration is documented and what file-system operations it enables.
- Performance characteristics on datasets larger than the 10 million-element example cited in the description.

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

nested array operations, variable-length list processing, json-like data manipulation, numpy for irregular data, ragged array library, hierarchical data structures, compiled nested data, nested-data, columnar-processing, physics-data

[View on SkillFed](https://skillfed.io/packages/awkward) · [View on PyPI](https://pypi.org/project/awkward/)