frozendict

What it is and what it does

frozendict is an immutable dictionary that behaves like a standard Python dict but cannot be modified after creation. It supports hashing (when all values are hashable) and pickling, making it suitable for use as dictionary keys or in sets. The package provides both a frozendict class with a dict-compatible API minus mutation methods, plus a deepfreeze utility that recursively converts nested mutable structures into their immutable equivalents.

The implementation guarantees true immutability—internal variables cannot be changed and are themselves immutable objects. It supports standard dict operations like get(), keys(), values(), items(), and fromkeys(), plus immutable variants like set() and delete() that return new frozendict instances. The | operator merges a frozendict with a regular dict, producing a new frozendict. An optional C extension is available for performance, but a pure Python fallback ensures broad compatibility.

Use it for:

• Use as dictionary keys or set members when you need hashable, immutable mappings for caching or memoization.
• Freeze nested data structures (lists, dicts, sets, custom objects) into immutable equivalents with deepfreeze().
• Define configuration or constant data that must not be accidentally modified during program execution.
• Serialize and deserialize immutable data structures via pickle while preserving hashability and immutability guarantees.
• Build functional-style code where data transformations return new frozendict instances rather than mutating state.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides an immutable, hashable dictionary implementation with a dict-like API, supporting operations like set(), delete(), and merge via the | operator while guaranteeing immutability.

Yes. frozendict is actively maintained, has zero known vulnerabilities, imposes no runtime dependencies, and solves a genuine need for immutable, hashable dictionaries in Python. The LGPL v3 copyleft license is a consideration if you're building proprietary software, but poses no barrier to use in open-source or internal projects. Install it if you need immutable mappings for hashing, thread safety, or functional programming patterns.

Install

frozendict on PyPI

pip install frozendict

uv add frozendict

poetry add frozendict

Installing frozendict

Before you install

Low friction: pure Python wheel available, no runtime dependencies, and actively maintained with recent releases. Optional C extension available for performance but not required.

License in practice

Licensed under LGPL v3 (copyleft): derivative works and modifications must be distributed under the same license, and source code must be made available to users who receive the software.

Quickstart

pip install frozendict

from frozendict import frozendict

fd = frozendict({'a': 1, 'b': 2})
print(hash(fd))  # hashable if all values are hashable
fd_new = fd.set('c', 3)  # returns new frozendict

All values must be hashable if you intend to hash the frozendict itself; attempting to hash a frozendict with unhashable values raises TypeError.

Verify before relying

• Performance comparison specifics: description mentions benchmarks but excerpt does not include actual numbers or scenarios.
• C extension performance impact: whether the optional C extension provides meaningful speedup for typical workloads is not quantified.
• deepfreeze recursion limits: maximum nesting depth or object graph size before hitting Python's recursion limit is not specified.

Package facts

Evidence: frozendict-2.4.7-py3-none-any.whl

Keywords: immutable, hashable, picklable, frozendict, dict, dictionary, map, Mapping, MappingProxyType, developers, stable, utility

Tags

More Libraries packages