immutables

What it is and what it does

immutables provides a Hash Array Mapped Trie–based immutable mapping for Python, implementing the collections.abc.Mapping interface. It's the same data structure used in CPython's contextvars module (PEP 567). The Map type is hashable and pickleable, making it suitable for use as dictionary keys or in concurrent contexts where mutability is a liability.

Since Maps are immutable, mutations return new derived Maps rather than modifying in place. The package offers both single-operation methods (set, delete) and a MapMutation context manager for batching changes efficiently before finalizing a new Map. It has no runtime dependencies and supports Python 3.8 and later across CPython implementations on macOS, Linux, and Windows.

Use it for:

• Use it for context variables and thread-local state where immutability prevents accidental mutations across async tasks
• Use it as keys in dictionaries or set members where hashability and immutability are required
• Use it in functional programming patterns where data transformations produce new collections without side effects
• Use it in concurrent or multi-threaded code to avoid synchronization overhead on shared data structures
• Use it for configuration objects that must remain unchanged after creation

Worth the install?

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

Provides an immutable mapping type backed by a Hash Array Mapped Trie (HAMT) data structure, offering O(log N) performance for get and set operations with hashable, comparable, and pickleable Map objects.

Yes, if you need immutable mappings for functional patterns, concurrent code, or as hashable dictionary keys. The HAMT implementation offers solid performance and is battle-tested in CPython itself. Install friction is moderate due to compiled extensions, but wheels cover all major platforms. Maintenance is aging (no release in 9+ months), so not suitable for projects requiring active upstream support, but stable for established use.

Install

immutables on PyPI

pip install immutables

uv add immutables

poetry add immutables

Installing immutables

Before you install

Medium install friction due to compiled C extensions across multiple platforms (macOS x86/arm, Linux x86/aarch64, Windows). No runtime dependencies. Last commit May 2025 but no release since October 2024; maintenance status is aging.

License in practice

Apache 2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

pip install immutables

import immutables

map1 = immutables.Map(a=1, b=2)
map2 = map1.set('a', 10)
print(map1['a'], map2['a'])  # 1 10

Verify before relying

• Whether the HAMT implementation matches CPython 3.7+ contextvars performance characteristics in practice
• Specific use-case performance gains over dict copy-on-write approaches beyond the referenced benchmark

Package facts

Evidence: immutables-0.21-cp310-cp310-macosx_10_9_x86_64.whl; immutables-0.21-cp310-cp310-macosx_11_0_arm64.whl; immutables-0.21-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; immutables-0.21-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl; immutables-0.21-cp310-cp310-musllinux_1_2_aarch64.whl; immutables-0.21-cp310-cp310-musllinux_1_2_x86_64.whl; immutables-0.21-cp310-cp310-win32.whl; immutables-0.21-cp310-cp310-win_amd64.whl; immutables-0.21-cp311-cp311-macosx_10_9_x86_64.whl; immutables-0.21-cp311-cp311-macosx_11_0_arm64.whl; immutables-0.21-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; immutables-0.21-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl; immutables-0.21-cp311-cp311-musllinux_1_2_aarch64.whl; immutables-0.21-cp311-cp311-musllinux_1_2_x86_64.whl; immutables-0.21-cp311-cp311-win32.whl; immutables-0.21-cp311-cp311-win_amd64.whl; immutables-0.21-cp312-cp312-macosx_10_13_x86_64.whl; immutables-0.21-cp312-cp312-macosx_11_0_arm64.whl; immutables-0.21-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; immutables-0.21-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Keywords: collections, immutable, hamt

Tags

More Libraries packages