---
id: immutables
version: "0.21"
license: Apache License, Version 2.0
license_treatment: permissive
maintenance: aging
---

# immutables — Immutable Collections

License: permissive · Maintenance: aging · Downloads: 2.9M/mo

## 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 above — 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

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

- License: Apache License, Version 2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: aging
- Downloads: 2.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

immutable mapping python, hamt hash array mapped trie, immutable dict alternative, functional data structures python, persistent hash map, copy-on-write collections, immutable collections library, immutable-data-structures, functional-programming, concurrency-safe

[View on SkillFed](https://skillfed.io/packages/immutables) · [View on PyPI](https://pypi.org/project/immutables/)