Frozendict
raw JSON → 2.4.7 verified Tue May 12 auth: no python install: verified
Frozendict is a Python library that provides a simple immutable dictionary implementation, mimicking Python's built-in `dict` but with unchangeable contents after creation. It offers hashability, allowing frozendict instances to be used as keys in other dictionaries or elements in sets. The library is actively maintained, with version 2.4.7 being the latest, and sees regular releases with performance improvements, new features like `deepfreeze`, and support for various architectures.
pip install frozendict Common errors
error TypeError: 'frozendict' object does not support item assignment ↓
cause You are attempting to modify a `frozendict` instance after its creation by assigning a new value to a key, which is not allowed because `frozendict` objects are immutable.
fix
Instead of modifying an existing
frozendict, create a new frozendict using the set() method or the union operator (|) to include the desired changes. error TypeError: 'frozendict' object doesn't support item deletion ↓
cause You are attempting to delete an item from a `frozendict` instance using `del`, which is not permitted as `frozendict` is immutable.
fix
To remove an item, create a new
frozendict using the delete() method, which returns a new instance without the specified key. error TypeError: Not all values are hashable. ↓
cause This error occurs when you try to calculate the hash of a `frozendict` (e.g., to use it as a key in another dictionary or as an element in a set) but one or more of its *values* are mutable and thus unhashable (e.g., lists, sets, or other mutable dictionaries). Keys must always be hashable.
fix
Ensure that all values within the
frozendict are themselves immutable and hashable (e.g., numbers, strings, tuples, frozenset, or other frozendict instances). If you need mutable nested structures, the frozendict itself cannot be hashed. error KeyError: 'some_key' ↓
cause You are trying to access a key in the `frozendict` that does not exist. This behavior is consistent with Python's built-in `dict` type.
fix
Before accessing an item, check if the key exists using
in operator, or use the .get(key, default_value) method to provide a fallback value if the key is not found. Warnings
breaking The `deepfreeze` function (introduced in v2.4.0) no longer modifies the original object in place. It now returns a new frozen object. ↓
fix If you relied on `deepfreeze` modifying the original object, you must now explicitly assign the result. For example, change `deepfreeze(my_obj)` to `my_obj = deepfreeze(my_obj)` or assign to a new variable.
gotcha Frozendict instances are only shallowly immutable. If a frozendict contains mutable nested objects (e.g., lists or dictionaries), these nested objects can be modified in place. Furthermore, if a frozendict contains any unhashable mutable nested objects, the frozendict itself will become unhashable, preventing its use as a dictionary key or in sets. ↓
fix To ensure deep immutability and hashability when using frozendict with potentially mutable nested data, apply `deepfreeze` to the data before creating the frozendict, or to the frozendict instance after creation. For example, `my_fd = frozendict(deepfreeze(my_dict))` or `my_hashable_fd = deepfreeze(my_fd)`.
gotcha The library typically uses a C extension for performance. In environments where C extensions are problematic or if you need to force the pure Python implementation for debugging, you can set an environment variable. ↓
fix Set the environment variable `FROZENDICT_PURE_PY=1` before running your Python script to force the pure Python implementation. This might lead to different performance characteristics.
gotcha Prior to version 2.4.7, pickling operations for the C extension could be significantly slower than the pure Python implementation or standard dicts. This was addressed with performance improvements in the latest release. ↓
fix Upgrade to frozendict v2.4.7 or later to benefit from improved pickling performance when using the C extension.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.01s 18.1M
3.10 alpine (musl) - - 0.01s 18.1M
3.10 slim (glibc) wheel 1.6s 0.01s 19M
3.10 slim (glibc) - - 0.01s 19M
3.11 alpine (musl) wheel - 0.01s 19.7M
3.11 alpine (musl) - - 0.02s 19.7M
3.11 slim (glibc) wheel 1.6s 0.01s 20M
3.11 slim (glibc) - - 0.01s 20M
3.12 alpine (musl) wheel - 0.01s 11.6M
3.12 alpine (musl) - - 0.01s 11.6M
3.12 slim (glibc) wheel 1.4s 0.02s 12M
3.12 slim (glibc) - - 0.01s 12M
3.13 alpine (musl) wheel - 0.01s 11.3M
3.13 alpine (musl) - - 0.01s 11.2M
3.13 slim (glibc) wheel 1.5s 0.01s 12M
3.13 slim (glibc) - - 0.01s 12M
3.9 alpine (musl) wheel - 0.01s 17.6M
3.9 alpine (musl) - - 0.01s 17.6M
3.9 slim (glibc) wheel 1.8s 0.01s 18M
3.9 slim (glibc) - - 0.01s 18M
Imports
- frozendict
from frozendict import frozendict - deepfreeze
from frozendict import deepfreeze
Quickstart last tested: 2026-04-24
from frozendict import frozendict, deepfreeze
# Create an immutable dictionary
fd = frozendict({'a': 1, 'b': 2, 'c': [3, 4]})
print(f"Initial frozendict: {fd}")
# Access elements like a regular dict
print(f"Value for 'a': {fd['a']}")
# Attempting to modify raises an error
try:
fd['d'] = 5
except TypeError as e:
print(f"Caught expected error on modification attempt: {e}")
# Note that nested mutable objects are still mutable unless deepfrozen
fd['c'].append(5)
print(f"Frozendict after modifying nested list: {fd}")
# Frozendict instances are hashable, so they can be dict keys
hash_map = {fd: 'this is a key'}
print(f"Using frozendict as a key: {hash_map[fd]}")
# Use deepfreeze for full immutability of nested structures
mutable_data = {'x': 10, 'y': [11, 12], 'z': {'key': 'value'}}
deep_frozen_data = deepfreeze(mutable_data)
print(f"Deep frozen data: {deep_frozen_data}")
try:
deep_frozen_data['y'].append(13) # This will now raise an error
except TypeError as e:
print(f"Caught expected error on deepfrozen nested modification: {e}")