---
id: flatdict
version: "4.1.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# flatdict — Python module for interacting with nested dicts as a single level dict with delimited keys.

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

## 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 above — 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

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

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

## Tags

flatten nested dictionaries, dict flattening library, composite key mapping, nested dict access, delimited key dictionary, flatten lists to dict, single-level dict wrapper, data-structure, dict-utility

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