Why does defining `__eq__` on a class make its instances unhashable?

Python enforces one invariant on hashing: **objects that compare equal must have the same hash**. If `a == b` is true then `hash(a) == hash(b)` must be true. Sets and dictionaries depend on it. A lookup computes the hash of the key, jumps to a bucket, and only compares candidates in that bucket with `==`. If two equal objects land in different buckets, the container simply never sees the match: you store an entry under one object and fail to find it with an equal one, silently. Object creation is where Python defends the invariant. When a class body defines `__eq__` and does not define `__hash__`, the class machinery sets `__hash__` to `None` in the new class's namespace. `None` is not callable, and `hash()` looks the slot up on the type, so `hash(instance)` raises `TypeError`, and every operation that hashes — adding to a `set`, using the object as a dict key, putting it in a `frozenset`, calling `functools.lru_cache` on a function that takes it — raises the same error. Nothing is deleted or optimised away; the attribute is deliberately poisoned so that the failure is loud and immediate instead of a lost dictionary entry three modules downstream. The rationale follows from what the two defaults do. `object.__hash__` derives a value from the object's identity, and `object.__eq__` is identity too, so the pair is consistent by construction. The moment you redefine equality in terms of fields, the inherited identity hash stops agreeing with it: two distinct instances that you have declared equal would hash differently. Rather than let you ship that, Python removes hashing until you say what should happen. **Restoring hashability, in order of preference.** 1. *Make the type immutable and hash the same fields you compare.* Define `__hash__` returning `hash((self.field_a, self.field_b))` over exactly the tuple of fields your `__eq__` uses. Now the invariant holds by construction. Do this only if those fields never change after construction — a key that mutates while it sits in a dict lands in the wrong bucket and is unreachable, and the dict will not notice. 2. *Let the standard library write both.* A dataclass declared with `frozen=True` generates `__eq__` and a matching `__hash__` from the compared fields, and blocks attribute assignment so the hash cannot drift. A plain `@dataclass` (which generates `__eq__` and leaves the instance mutable) sets `__hash__` to `None`, exactly like a hand-written `__eq__` would. 3. *Keep identity hashing on purpose.* Writing `__hash__ = object.__hash__` in the class body restores the inherited identity hash. This is legitimate only when you understand the consequence: two objects that compare equal will usually hash differently, so the type is safe to put in a dict only if you never rely on an equal-but-distinct key finding the entry. Graph nodes and other identity-first types with a convenience `__eq__` sometimes take this route; most domain value types should not. **Inheritance follows the same rule.** The `__hash__ = None` assignment happens per class body, so a subclass that overrides `__eq__` becomes unhashable even if its base defined a perfectly good `__hash__`. If the subclass's equality is compatible, re-declare `__hash__ = Base.__hash__` explicitly; the explicitness is the point. **Two symptoms to recognise in an interview.** First, `TypeError` naming the type as unhashable the first time an instance meets a set or a dict key — the usual trigger is calling `set()` on a list of newly value-ified objects, or memoising a function on them. Second, and worse, no error at all: someone "fixed" the first symptom by adding a `__hash__` that hashes a subset of the compared fields, or by hashing mutable state. That version satisfies the interpreter and violates the contract on the data, producing duplicates in a set and lookups that miss intermittently, which is far harder to diagnose than the original `TypeError`. **Checking it yourself.** `SomeClass.__hash__` is `None` for the broken case — that single expression tells you whether a class was silently made unhashable, and it is the fastest thing to inspect when a type that used to work in a set stops working after someone added value equality to it. The complementary check is behavioural: build two equal instances and assert both `a == b` and `hash(a) == hash(b)`, then assert that `{a, b}` has exactly one element. Those three assertions encode the whole contract, and they are worth writing the day you give a class value semantics.