Install & Compatibility
Where this runs
tested against v4.1.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.010s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.006s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FlatDict
✓ from flatdict import FlatDict
FlatterDict
✓ from flatdict import FlatterDict
__version__
✓ from importlib.metadata import version; version('flatdict')
✗ import flatdict; flatdict.__version__
`__version__` attribute was removed in flatdict 4.1.0. Use `importlib.metadata.version` for programmatic version retrieval.
This quickstart demonstrates the basic usage of `FlatDict` and `FlatterDict`. It shows how to create flattened dictionaries, access and modify values using delimited keys, add new keys, and convert them back to nested dictionaries. It also illustrates how to correctly retrieve the library version after the removal of the `__version__` attribute in `flatdict` 4.1.0.
import flatdict
import pprint
from importlib.metadata import version
# Get the library version (new way, as __version__ was removed in 4.1.0)
print(f"flatdict version: {version('flatdict')}")
# Example with FlatDict
nested_dict = {
'user': {
'name': 'Alice',
'contact': {'email': 'alice@example.com', 'phone': '123-456-7890'}
},
'app_settings': {'theme': 'dark'}
}
flat = flatdict.FlatDict(nested_dict)
print("\nFlatDict example:")
print(f"Original nested dict: {nested_dict}")
print(f"Flat dict representation: {flat}")
# Accessing values with delimited keys
print(f"Accessing 'user:name': {flat['user:name']}")
print(f"Accessing 'user:contact:email': {flat['user:contact:email']}")
# Modifying values
flat['app_settings:theme'] = 'light'
print(f"Modified 'app_settings:theme': {flat['app_settings:theme']}")
# Adding new values
flat['new:key'] = 'new_value'
print(f"Added 'new:key': {flat['new:key']}")
# Converting back to nested dict
print("\nConverted back to nested dict (FlatDict.as_dict()):")
pprint.pprint(flat.as_dict())
# Example with FlatterDict (handles lists/tuples by enumerating elements)
nested_with_list = {
'items': ['apple', 'banana', {'fruit': 'cherry'}],
'settings': {'verbose': True}
}
flatter = flatdict.FlatterDict(nested_with_list)
print("\nFlatterDict example:")
print(f"Original nested dict with list: {nested_with_list}")
print(f"Flatter dict representation: {flatter}")
# Accessing list elements using numerical keys
print(f"Accessing 'items:0': {flatter['items:0']}")
print(f"Accessing 'items:2:fruit': {flatter['items:2:fruit']}")
# Converting back to nested dict
print("\nConverted back to nested dict (FlatterDict.as_dict()):")
pprint.pprint(flatter.as_dict())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flatdict'
The `flatdict` library has not been installed in your Python environment.
TypeError: Assignment to invalid type for key {key_name}
This error often occurs when attempting to assign a value to a flattened key that was originally part of a list or tuple in a `FlatterDict`, and the new assignment is incompatible with how `FlatterDict` manages array-like structures internally.
fixEnsure that when modifying elements that originated from lists or tuples in a `FlatterDict`, you either reassign the entire (sub)list/tuple or access its elements as if they were part of a dictionary with integer keys. For example, if 'list_key' was originally a list, `flatter_dict['list_key:0'] = 'new_value'` is generally correct, but trying to assign a non-indexable type to a key representing an array segment can fail. It might be necessary to convert the `FlatterDict` to a regular dict using `as_dict()` for complex modifications, then re-flatten if needed, or reconstruct the problematic section.
KeyError: '{key}'
This error occurs when attempting to access or remove a key that does not exist in the `FlatDict` or `FlatterDict`.
fixBefore accessing or manipulating a key, check for its existence using `if 'key' in flat_dict:` or use methods like `flat_dict.get('key', default_value)` or `flat_dict.pop('key', default_value)` which allow specifying a default return value instead of raising a `KeyError`. AttributeError: module 'collections' has no attribute 'MutableMapping'
This issue arises in Python 3.9 and newer versions where `collections.MutableMapping` has been moved to `collections.abc.MutableMapping`. Older versions of `flatdict` or other libraries that import `flatdict` might not correctly handle this change.
fixUpgrade `flatdict` to its latest version (4.1.0 or newer) which includes compatibility fixes for this change. If the issue persists due to other dependencies, ensure all related packages are updated to be compatible with your Python version.
Upgrade
Version history
4.1.0latest on PyPI · released Feb 15, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.