flatdict

What it is and what it does

FlatDict provides two dict subclasses—FlatDict and FlatterDict—that present nested dictionaries as a single flat level while preserving access to the original structure. When you wrap a nested dict, keys are automatically flattened using a delimiter (colon by default), so a path like `{'foo': {'bar': 'baz'}}` becomes accessible as `{'foo:bar': 'baz'}`. You can read and write using either the composite key or the nested path interchangeably.

FlatterDict extends this to sequences: lists and tuples are also flattened by converting indices to keys, so `{'list': ['a', 'b', 'c']}` becomes `{'list:0': 'a', 'list:1': 'b', 'list:2': 'c'}`. This is useful when you need to work with deeply nested or mixed structures as a flat key-value store—common in configuration handling, data transformation, or API response normalization.

Use it for:

• Normalize deeply nested JSON or config objects into a flat key-value store for easier iteration or lookup.
• Convert API responses with nested structures into a single-level dict for database storage or serialization.
• Flatten configuration hierarchies to pass as environment variables or command-line arguments.
• Transform nested data structures into a format suitable for CSV export or tabular processing.
• Simplify access patterns in code that needs to work with both flat and nested representations simultaneously.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Flattens nested dictionaries into single-level dicts with delimited composite keys, and optionally flattens lists and tuples by index.

Yes. This is a stable, well-maintained utility with zero dependencies, no known vulnerabilities, and a permissive license. Install it if you regularly work with nested dicts and need a lightweight, transparent way to flatten them. The low friction and broad Python version support make it a safe, practical choice.

Install

flatdict on PyPI

pip install flatdict

uv add flatdict

poetry add flatdict

Installing flatdict

Before you install

Low friction: pure Python wheel with no runtime dependencies. Active maintenance with a recent release (2026-02-15) and a commit history through 2026-06-12. Supports Python 3.10 through 3.14 and PyPy.

License in practice

BSD-3-Clause (permissive): you can use, modify, and distribute this package freely in proprietary or open-source projects with minimal restrictions, provided you include the license notice.

Quickstart

pip install flatdict

import flatdict

value = flatdict.FlatDict({'foo': {'bar': 'baz'}})
print(value['foo:bar'])  # 'baz'
print(value['foo']['bar'])  # 'baz'

Package facts

Evidence: flatdict-4.1.0-py3-none-any.whl

Tags

More Libraries packages