Introduction

TypeError: unhashable type: 'dict' means Python tried to use a dictionary in a place that requires a hashable object. The usual examples are dictionary keys, set elements, or other structures based on hashing. The real reason dictionaries fail here is not arbitrary language design; it is that dictionaries are mutable, and mutable objects are generally unsafe as hash keys because their contents can change after insertion.

Why Hashability Matters

Hash-based containers such as dict and set rely on objects having a stable hash value. If an object could change in a way that changes its hash after insertion, the container would no longer know where to find it reliably.

That is why immutable objects such as strings, tuples of hashable values, and integers are hashable, while mutable dictionaries are not.

A Simple Failure Example

This raises the error:

key = {"name": "Ana"}
lookup = {}
lookup[key] = "user"

Python refuses because key is a dictionary.

The same issue appears with sets:

items = set()
items.add({"name": "Ana"})

Again, a dictionary cannot be added because set elements must also be hashable.

Why Dictionaries Are Unhashable

A dictionary can change at any time.

data = {"x": 1}
data["y"] = 2

If Python allowed that dictionary to be used as a key, its identity in a hash table would become unsafe once its contents changed. So Python prevents the misuse up front.

Use An Immutable Representation Instead

If what you really need is a dictionary-like value as a key, convert it into a stable immutable form.

One common approach is to use a tuple of sorted items.

1data = {"name": "Ana", "role": "admin"}
2key = tuple(sorted(data.items()))
3
4lookup = {key: "user"}
5print(lookup[key])

This works because the tuple is immutable and the sorted key-value pairs give a deterministic representation.

frozenset Can Work Too

Another common representation is a frozenset of items.

1data = {"name": "Ana", "role": "admin"}
2key = frozenset(data.items())
3
4lookup = {key: "user"}
5print(lookup[key])

This is often convenient when ordering does not matter and all keys and values inside the dictionary are themselves hashable.

Be Careful With Nested Structures

If the dictionary contains nested lists or nested dictionaries, simply calling tuple(sorted(data.items())) may still fail because the nested values may themselves be unhashable.

In those cases, you need a deeper normalization strategy, such as recursively converting nested lists to tuples and nested dictionaries to sorted tuples or frozensets.

That is usually a sign to step back and ask whether a different data model would be clearer.

Sometimes The Real Fix Is “Do Not Use It As A Key”

The correct solution is not always to force a dictionary into a hashable form. Sometimes the error reveals a design issue.

For example, if you are trying to use a whole mutable configuration object as a key in a cache, the better design might be:

• extract only the fields that define identity,
• build a stable key from those fields,
• keep the full dictionary as a value instead.

That usually leads to cleaner code than turning every mutable object into an artificial key structure.

Common Pitfalls

• Using a dictionary directly as a dict key or set element.
• Converting to a tuple or frozenset without checking whether nested values are still unhashable.
• Confusing “unhashable” with “unusable” instead of choosing a stable immutable representation.
• Forcing hashability when the real issue is poor key design.
• Forgetting that lists inside the dictionary may also block the conversion strategy.

Summary

• The error occurs because dictionaries are mutable and therefore not hashable.
• Hash-based containers require stable hash values.
• Convert dictionary content to an immutable representation such as a tuple of sorted items or a frozenset when appropriate.
• For nested mutable data, you may need recursive normalization.
• Often the best fix is to redesign the key, not just to encode the entire dictionary mechanically.