---
id: flatten-dict
version: "0.5.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# flatten-dict — A flexible utility for flattening and unflattening dict-like objects in Python.

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

## What it is and what it does

flatten-dict provides two core functions: `flatten()` transforms nested dict-like objects into a single-level dictionary with composite keys, and `unflatten()` reverses the process. The package supports multiple key-joining strategies—tuples, filesystem paths, underscores, dots, or custom callables—letting you choose how nested keys combine. You can also enumerate sequences (lists) as indexed keys, preserve or discard empty containers, limit flattening depth, and invert keys and values.

The package is useful when you need to serialize hierarchical data into flat form for storage, comparison, or API transmission, or when you need to reconstruct nested structures from flat representations. It has no external dependencies and works across modern Python versions.

Use it for:

- Convert nested configuration objects into flat key-value pairs for environment variable mapping or flat file storage.
- Flatten API responses or JSON payloads to extract all leaf values with their full key paths.
- Transform flat dictionaries back into nested structures for hierarchical data reconstruction.
- Enumerate list indices as keys to treat sequences uniformly with nested dicts during flattening.
- Customize key joining with domain-specific delimiters or logic via callable reducers.

## Worth the install?

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

Converts nested dictionaries into flat key-value pairs and back, with customizable key-joining strategies like tuples, paths, underscores, or dots.

Yes. The package is lightweight, dependency-free, actively maintained, has no known vulnerabilities, and solves a common data-transformation problem with a clean API. Install it if you regularly work with nested dictionaries or need flexible dict flattening/unflattening.

## Install

pip install flatten-dict
uv add flatten-dict
poetry add flatten-dict

## Installing flatten-dict

Before you install: Low friction: pure Python wheel with no runtime dependencies and active maintenance (last commit 2026-08-06, release 108 days ago). Supports Python 3.10–3.14.

License in practice: MIT license (permissive); you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

from flatten_dict import flatten, unflatten

nested = {'a': '0', 'b': {'a': '1.0', 'b': '1.1'}}
flat = flatten(nested, reducer='dot')
# {'a': '0', 'b.a': '1.0', 'b.b': '1.1'}

reconstructed = unflatten(flat, splitter='dot')
# {'a': '0', 'b': {'a': '1.0', 'b': '1.1'}}

## Package facts

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

## Tags

flatten nested dict, unflatten dictionary, nested dict to flat, dict key joining, hierarchical dict flattening, dict structure transformation, nested mapping utilities, dict-utilities, data-transformation

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