Immutability & Hashability

Hashable objects can live in sets and dict keys. Immutability is the usual way to guarantee hash stability - if an object's value changes after insertion, lookups break silently.

Recipe

key = (42, "ada")          # tuple of hashables - OK
tags = frozenset(["a", "b"])  # hashable set
 
# NOT hashable:
# bad = ([1, 2],)          # list inside tuple
# { [1, 2]: "x" }          # list as key

When to reach for this:

• Using objects as dict keys or set members
• Building caches keyed by arguments
• Designing value objects in domain models
• Debugging TypeError: unhashable type

Working Example

from dataclasses import dataclass
 
@dataclass(frozen=True)
class UserId:
    value: int
 
def cache_key(*parts: object) -> tuple:
    return tuple(parts)
 
def dedupe_records(records: list[tuple[str, int]]) -> list[tuple[str, int]]:
    seen: set[tuple[str, int]] = set()
    unique: list[tuple[str, int]] = []
    for record in records:
        if record not in seen:
            seen.add(record)
            unique.append(record)
    return unique
 
class Point:
    __slots__ = ("x", "y")
 
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y
 
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Point):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)
 
    def __hash__(self) -> int:
        return hash((self.x, self.y))
 
if __name__ == "__main__":
    index: dict[UserId, str] = {UserId(1): "Ada"}
    print(index[UserId(1)])
    print(dedupe_records([("a", 1), ("a", 1), ("b", 2)]))

What this demonstrates:

• frozen=True dataclass is hashable when fields are hashable
• Tuple cache keys combine hashable parts
• Custom class implements matching __eq__ and __hash__
• __slots__ reduces memory for many small objects

Deep Dive

How It Works

• __hash__ - Integer digest used to locate bucket in hash table.
• __eq__ - Equality must agree with hash: equal objects equal hash.
• Immutable builtins - int, str, bytes, tuple (if elements hashable), frozenset.
• Mutable builtins - list, dict, set, bytearray - no stable hash.
• User classes - Default instance hash is by id unless overridden.

Hashability Rules

Python Notes

# dataclasses with unsafe_hash generates __hash__ from fields
@dataclass(frozen=True)
class Coord:
    x: int
    y: int
 
# disable hash when mutable semantics needed
@dataclass(eq=True, frozen=False)
class Buffer:
    data: bytearray

Gotchas

• Mutable dataclass in set - Dataclass mutable → unhashable by default. Fix: frozen=True or exclude from sets.
• Custom eq without hash - Python sets __hash__ = None. Fix: Implement consistent __hash__ or use functools.cached_property patterns carefully.
• Hash changes when fields change - Violates dict/set contract. Fix: Immutable objects only as keys.
• NaN floats - float('nan') hashable but nan != nan. Fix: Avoid NaN keys.
• Tuples with mutable lists inside - Tuple hashable but list content can mutate breaking invariants if exposed. Fix: Do not mutate nested mutables used in keys.

Alternatives

FAQs

Related

• Dictionaries - key requirements
• Sets & Frozensets - frozenset usage
• dataclasses - frozen records
• Dunder / Magic Methods - eq and hash

External Related Links

• Python Language Reference - Formal description of Python syntax and core semantics.
• Official Python Documentation - The definitive source (Tutorial, Library Reference, Language Reference, HOWTOs).
• Real Python - In-depth tutorials, courses, and practical guides.
• Fluent Python (2nd Edition) - Intermediate to advanced Python idioms (Luciano Ramalho).
• The Quick Python Book (4th Edition) - Concise Python overview (Naomi Ceder).

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.