---
id: json-normalize
version: "1.1.0"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# json-normalize — Recursively flattens a JSON-like structure into a list of flat dicts.

License: permissive · Maintenance: dormant · Downloads: 80.2K/mo

## What it is and what it does

json_normalize takes a nested JSON-like structure—dicts, lists, generators, and other iterables—and flattens it into a sequence of flat dictionaries. Each key in the output is a dot-joined path from the root to a leaf value. The package handles the tricky case of data association: when nested dicts share a common dict ancestor, their data flows together into the same output records; when they share a list ancestor, they remain separate. When multiple independent lists exist in different branches, you can choose how to combine them: chain them sequentially, compute their Cartesian product, or drop problematic branches entirely.

The function is configurable: you can customize the path joiner (dot, arrow, or a callable), freeze certain nodes to prevent recursive normalization below them, drop nodes by name, and control list combination behavior. It accepts generators and lazy iterables as input, making it useful for streaming or memory-constrained scenarios.

Use it for:

- Convert API responses with nested objects and arrays into flat rows suitable for CSV export or database insertion
- Flatten configuration files or metadata structures to extract all leaf values with their full paths
- Denormalize time-series data where measurements contain nested sensor readings and metadata
- Transform hierarchical log entries or event objects into tabular format for analysis
- Prepare nested JSON for pandas DataFrame construction by generating flat dict records

## Worth the install?

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

Recursively flattens nested JSON-like structures (dicts and iterables) into a sequence of flat dictionaries with dot-joined keys, handling multiple lists through configurable combination strategies.

Yes, if you need to flatten nested JSON into flat dicts. The package is stable, dependency-free, and permissively licensed. Dormant maintenance is acceptable for a focused utility with no known vulnerabilities, but verify it handles your specific nesting patterns (especially multiple list branches) before committing to production use.

## Install

pip install json-normalize
uv add json-normalize
poetry add json-normalize

## Installing json-normalize

Before you install: Low friction: pure Python wheel with no runtime dependencies. Maintenance is dormant (last commit 2024-09-25, 869 days since release), but the package is marked Production/Stable and has received no security reports.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal attribution requirements—suitable for any project type.

Quickstart:

from json_normalize import json_normalize

json_like = {"city": "Stockholm", "coords": {"lat": 59.331924, "long": 18.062297}}
result = list(json_normalize(json_like))
# Output: [{'city': 'Stockholm', 'coords.lat': 59.331924, 'coords.long': 18.062297}]

Verify before relying:

- Whether dormant maintenance status (869 days since last release) poses a risk for future Python or dependency ecosystem changes
- Performance characteristics on deeply nested or very large JSON structures

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 80.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

flatten nested json, json to flat dict, denormalize json structure, recursive json flattening, nested dict normalization, json path flattening, hierarchical json converter, json-processing, data-transformation

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