---
id: flatten-json
version: "0.1.14"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# flatten-json — Flatten JSON objects

License: permissive · Maintenance: dormant · Downloads: 2.8M/mo

## What it is and what it does

flatten_json is a lightweight utility that converts nested JSON objects into single-level dictionaries by joining keys with a separator (default underscore), and can reverse the process. It's particularly useful when you need to convert hierarchical data into tabular form—for example, preparing nested API responses for export or working with tabular data structures. The package provides three main functions: flatten() to collapse nested structures, unflatten() to reconstruct them, and unflatten_list() to handle cases where integer-indexed keys should become lists. It supports customizable separators and can selectively ignore root keys to skip unnecessary processing on large objects.

Use it for:

- Convert nested API JSON responses into flat dictionaries for export or database import
- Prepare hierarchical JSON data for tabular data structures with automatic column flattening
- Reverse-flatten previously flattened data back to its original nested structure
- Filter out unwanted nested branches during flattening using root_keys_to_ignore parameter
- Command-line JSON transformation via pipe (echo '{"a": {"b": 1}}' | flatten_json)

## Worth the install?

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

Converts nested JSON objects into flat key-value dictionaries and reverses the process, useful for preparing hierarchical data for tabular formats.

Yes, if you regularly work with nested JSON and need to convert it to tabular formats. The package is stable, has no known vulnerabilities, and low install friction. However, maintenance is dormant (no updates since 2023-11-01); if you need active support or encounter edge cases, consider whether a maintained alternative is necessary. For straightforward flatten/unflatten tasks, this is a solid choice.

## Install

pip install flatten-json
uv add flatten-json
poetry add flatten-json

## Installing flatten-json

Before you install: Low friction; depends only on six. Dormant maintenance status (last commit 2023-11-01, 1022 days since release) means no active development, but the package is stable.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

from flatten_json import flatten

dic = {"a": 1, "b": {"c": 2}}
flattened = flatten(dic)
# Result: {'a': 1, 'b_c': 2}

Verify before relying:

- Whether the package handles edge cases in deeply nested structures or circular references gracefully
- Performance characteristics on very large or complex JSON objects
- Compatibility with modern Python versions beyond what the fact sheet specifies

## Package facts

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

## Tags

flatten nested json, json to flat dictionary, unflatten json, json hierarchy to table, nested object flattening, json denormalization, convert json to dataframe, json-processing, data-transformation

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