{"id":866,"library":"frozendict","title":"Frozendict","description":"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.","status":"active","version":"2.4.7","language":"python","source_language":"en","source_url":"https://github.com/Marco-Sulla/python-frozendict","tags":["immutable","dictionary","hashable","collection","datastructure"],"install":[{"cmd":"pip install frozendict","lang":"bash","label":"Install frozendict"}],"dependencies":[],"imports":[{"symbol":"frozendict","correct":"from frozendict import frozendict"},{"note":"Introduced in v2.4.0 for recursively freezing objects.","symbol":"deepfreeze","correct":"from frozendict import deepfreeze"}],"quickstart":{"code":"from frozendict import frozendict, deepfreeze\n\n# Create an immutable dictionary\nfd = frozendict({'a': 1, 'b': 2, 'c': [3, 4]})\nprint(f\"Initial frozendict: {fd}\")\n\n# Access elements like a regular dict\nprint(f\"Value for 'a': {fd['a']}\")\n\n# Attempting to modify raises an error\ntry:\n    fd['d'] = 5\nexcept TypeError as e:\n    print(f\"Caught expected error on modification attempt: {e}\")\n\n# Note that nested mutable objects are still mutable unless deepfrozen\nfd['c'].append(5)\nprint(f\"Frozendict after modifying nested list: {fd}\")\n\n# Frozendict instances are hashable, so they can be dict keys\nhash_map = {fd: 'this is a key'}\nprint(f\"Using frozendict as a key: {hash_map[fd]}\")\n\n# Use deepfreeze for full immutability of nested structures\nmutable_data = {'x': 10, 'y': [11, 12], 'z': {'key': 'value'}}\ndeep_frozen_data = deepfreeze(mutable_data)\nprint(f\"Deep frozen data: {deep_frozen_data}\")\ntry:\n    deep_frozen_data['y'].append(13) # This will now raise an error\nexcept TypeError as e:\n    print(f\"Caught expected error on deepfrozen nested modification: {e}\")","lang":"python","description":"Demonstrates creating a frozendict, accessing elements, its immutability and hashability, and the use of `deepfreeze` for recursive immutability."},"warnings":[{"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.","message":"The `deepfreeze` function (introduced in v2.4.0) no longer modifies the original object in place. It now returns a new frozen object.","severity":"breaking","affected_versions":">=2.4.2"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":">=2.4.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.3.9"},{"fix":"Upgrade to frozendict v2.4.7 or later to benefit from improved pickling performance when using the C extension.","message":"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.","severity":"gotcha","affected_versions":"<2.4.7"}],"env_vars":null,"last_verified":"2026-05-12T20:32:33.634Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Instead of modifying an existing `frozendict`, create a new `frozendict` using the `set()` method or the union operator (`|`) to include the desired changes.","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.","error":"TypeError: 'frozendict' object does not support item assignment"},{"fix":"To remove an item, create a new `frozendict` using the `delete()` method, which returns a new instance without the specified key.","cause":"You are attempting to delete an item from a `frozendict` instance using `del`, which is not permitted as `frozendict` is immutable.","error":"TypeError: 'frozendict' object doesn't support item deletion"},{"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.","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.","error":"TypeError: Not all values are hashable."},{"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.","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.","error":"KeyError: 'some_key'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.4.7","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"2.4.7","pypi_latest":"2.4.7","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"18.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"18.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"19.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.4,"disk_size":"19.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"11.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"11.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.4,"import_time_s":0.02,"mem_mb":0.4,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"11.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"11.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.01,"mem_mb":0.3,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.3,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"17.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"17.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.8,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"frozendict","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}