Introduction

In Python, an object is hashable if it can produce a hash value that stays stable during its lifetime and if it participates in equality in a way that is consistent with that hash. Hashable objects can be used as dictionary keys and set elements.

That definition matters because Python dictionaries and sets are hash tables. They use the object's hash to decide where to store it, and they use equality to confirm whether two objects should be treated as the same key.

The Basic Rule

An object is considered hashable when both of these are true:

• its hash value does not change while the object is being used,
• if a == b, then hash(a) == hash(b).

You can inspect hashability with Python's built-in hash():

print(hash("hello"))
print(hash(42))
print(hash((1, 2, 3)))

But this fails for mutable built-in containers such as lists:

print(hash([1, 2, 3]))

That raises TypeError because a list can change after insertion, which would make it unsafe as a dictionary key.

Why Mutability Usually Matters

Imagine putting a list into a hash table as a key and then changing its contents. The object might no longer belong in the same hash bucket. That would break dictionary and set behavior.

This is why immutable built-in types such as int, str, and tuple are commonly hashable, while mutable types such as list, dict, and set are not.

There is one important nuance: immutability alone is not enough. A tuple is hashable only if all of its elements are hashable.

print(hash((1, "a", 3.14)))
print(hash((1, [2, 3])))

The second line fails because the tuple contains a list, and the tuple's hash depends on its contents.

Hashability and Dictionary Keys

Dictionary keys must be hashable because Python needs fast lookup. The same is true for members of a set.

1counts = {}
2counts["apple"] = 3
3counts[(2025, 3, 8)] = "report day"
4
5seen = {("x", 1), ("y", 2)}
6print(counts)
7print(seen)

These work because strings and tuples of hashable values are hashable.

Custom Objects

User-defined objects are hashable by default only if they keep the default identity-based behavior. Once you define custom equality, hash behavior becomes a design decision.

Here is a clean pattern using a frozen dataclass:

1from dataclasses import dataclass
2
3
4@dataclass(frozen=True)
5class Point:
6    x: int
7    y: int
8
9
10p = Point(3, 4)
11print(hash(p))

Because the dataclass is frozen, its fields cannot be mutated after creation, and Python can safely provide consistent hashing behavior.

Equality and Hash Must Agree

The most important custom-class rule is this: if two objects compare equal, they must produce the same hash. Python relies on that contract when storing keys in dictionaries and sets.

You do not need every unequal object to have a different hash. Collisions are allowed. What you do need is consistency between __eq__ and __hash__, or dictionary behavior becomes incorrect and confusing.

Common Pitfalls

• Assuming all tuples are hashable. They are only hashable if every element inside them is hashable.
• Confusing hashable with unique. Different objects can have the same hash value; Python handles collisions separately.
• Implementing custom __eq__ without understanding how it affects __hash__.
• Trying to use lists or dictionaries as dictionary keys.
• Treating hashability as a performance feature only. It is also a correctness contract about equality and stability.

Summary

• Hashable objects can be used as dictionary keys and set members.
• A hashable object must have a stable hash and an equality rule consistent with that hash.
• Immutable built-ins are often hashable, while mutable built-ins usually are not.
• Tuples are hashable only when all their contents are hashable.
• For custom classes, frozen immutable designs make safe hashing much easier.