flatten-dict

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 on this page — 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

flatten-dict on PyPI

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

Evidence: flatten_dict-0.5.0-py3-none-any.whl

Tags

More Utilities packages