Install & Compatibility
Where this runs
tested against v0.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.122s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.110s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flatten
✓ from flatten_dict import flatten
unflatten
✓ from flatten_dict import unflatten
make_splitter
✓ from flatten_dict.splitters import make_splitter
✗ from flatten_dict.splitter import make_splitter
The 'splitter' module was deprecated in 0.4.0 in favor of 'splitters' (plural).
make_reducer
✓ from flatten_dict.reducers import make_reducer
✗ from flatten_dict.reducer import make_reducer
The 'reducer' module was deprecated in 0.4.0 in favor of 'reducers' (plural).
This quickstart demonstrates basic flattening and unflattening of a nested dictionary using the default underscore delimiter, and then shows how to use a custom dot delimiter for flattening.
from flatten_dict import flatten, unflatten
data = {
'user': {
'name': 'Alice',
'address': {'city': 'Wonderland', 'zip': '12345'}
},
'products': [
{'id': 1, 'item': 'Tea Cup'},
{'id': 2, 'item': 'Rabbit Hole'}
]
}
# Flatten the dictionary with default underscore delimiter
flat_data = flatten(data)
print('Flattened (default underscore):')
print(flat_data)
# Expected: {'user_name': 'Alice', 'user_address_city': 'Wonderland', 'user_address_zip': '12345', 'products_0_id': 1, 'products_0_item': 'Tea Cup', 'products_1_id': 2, 'products_1_item': 'Rabbit Hole'}
# Unflatten it back
unflat_data = unflatten(flat_data)
print('\nUnflattened back:')
print(unflat_data)
# Expected: {'user': {'name': 'Alice', 'address': {'city': 'Wonderland', 'zip': '12345'}}, 'products': [{'id': 1, 'item': 'Tea Cup'}, {'id': 2, 'item': 'Rabbit Hole'}]}
# Flatten with a custom dot delimiter
from flatten_dict.splitters import dot_splitter
flat_data_dot = flatten(data, splitter=dot_splitter)
print('\nFlattened (dot splitter):')
print(flat_data_dot)
# Expected: {'user.name': 'Alice', 'user.address.city': 'Wonderland', 'user.address.zip': '12345', 'products.0.id': 1, 'products.0.item': 'Tea Cup', 'products.1.id': 2, 'products.1.item': 'Rabbit Hole'}
Debug
Known issues
breakingThe modules `flatten_dict.splitter` and `flatten_dict.reducer` were deprecated in version 0.4.0 in favor of their pluralized counterparts, `flatten_dict.splitters` and `flatten_dict.reducers`. Direct imports from the old paths will raise a DeprecationWarning and may break in future versions.fixUpdate your imports: `from flatten_dict.splitter import ...` to `from flatten_dict.splitters import ...` and similarly for `reducer` to `reducers`.
affects: >=0.4.0
gotchaBy default, `flatten()` uses an underscore (`_`) as a delimiter and automatically enumerates items in lists/tuples. This might not be the desired key format, especially if keys already contain underscores or you prefer a different delimiter like a dot (`.`).fixSpecify a custom `splitter` (for `flatten`) and `reducer` (for `unflatten`) when calling the functions. For example, use `splitter=dot_splitter` from `flatten_dict.splitters` for dot-separated keys, or `make_splitter('your_delimiter')` for custom delimiters. affects: All
gotchaThe `enumerate_types` parameter in `flatten()` (defaulting to `(list, tuple)`) will turn list/tuple indices into parts of the flattened key (e.g., `products_0_id`). If you want to prevent enumeration for certain types or handle them differently, you need to adjust this parameter.fixSet `enumerate_types=()` to disable enumeration for all types, or provide a tuple of specific types that should be enumerated (e.g., `enumerate_types=(list,)` to enumerate only lists, not tuples).
affects: All
gotchaFor Python versions prior to 3.8, `importlib-metadata` is a required dependency to ensure good import performance. While `pathlib2` is optional for Python < 3.4, not having these can lead to slower performance or potentially missed functionality on older Python versions.fixEnsure `importlib-metadata` is installed (`pip install importlib-metadata`) when using Python < 3.8. Consider installing `pathlib2` if on Python < 3.4 for full compatibility.
affects: <3.8 (importlib-metadata), <3.4 (pathlib2)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flatten_dict'
The `flatten-dict` library is installed using `pip install flatten-dict`, but the Python module to import is `flatten_dict`. This error occurs if the package is not installed or if there's a typo in the import statement.
fixFirst, ensure the library is installed: `pip install flatten-dict`. Then, import it correctly: `from flatten_dict import flatten, unflatten`.
AttributeError: 'bool' object has no attribute 'items'
This error typically occurs when the `flatten` function encounters a non-dictionary object (like a boolean, string, or integer) in a nested structure where it expects another dictionary to iterate over using `.items()`. This can happen if your input dictionary contains unexpected data types or if the default flattening logic is applied to structures not intended to be fully flattened as dictionaries.
fixEnsure that nested structures are dict-like where `flatten` expects them. If your dictionary contains lists, tuples, or other iterables that you want to flatten, use the `enumerate_types` parameter (e.g., `flatten(my_dict, enumerate_types=(list,))`) to tell `flatten-dict` how to handle them. For other non-dict types, ensure they are at the 'leaf' level or handle them with custom reducers if complex flattening is required.
unflatten makes dicts instead of lists when index is list index
When flattening a dictionary containing lists, `flatten-dict` by default might not store the list indices in a way that `unflatten` can correctly reconstruct them as lists. Instead, `unflatten` might recreate them as dictionaries with integer keys.
fixTo ensure `unflatten` correctly reconstructs lists, you must explicitly tell `flatten` to enumerate list (and/or tuple) types during the flattening process using the `enumerate_types` parameter. For example: `flat_dict = flatten(original_dict, enumerate_types=(list,))`. Then, `unflatten(flat_dict)` will restore lists correctly.
Upgrade
Version history
0.5.0latest on PyPI · released Apr 28, 2026
Audit
Dependencies
importlib-metadatarequiredRequired for Python versions < 3.8 to ensure optimal import performance.
pathlib2optionalOptional dependency for Python versions < 3.4. If not installed, some file path related functionalities might be limited.