What Is a frozenset?

A frozenset is an immutable set. It holds unique hashable items and supports all the read operations of a set, but none of the mutating ones.

frozen = frozenset({1, 2, 3})
print(type(frozen).__name__)      # frozenset
print(sorted(frozen))             # [1, 2, 3]

# It can be a dictionary key, because it is hashable
cache = {frozen: "cached value"}
print(cache[frozenset({3, 2, 1})])   # cached value

try:
    cache[set([1, 2, 3])]
except TypeError as err:
    print("TypeError:", err)

The dictionary lookup with a freshly built frozenset succeeds, because a frozenset hashes by its contents and two frozensets with the same elements are equal and hash the same. The lookup with a plain set fails with a TypeError saying that a set is unhashable, which is the key difference between the two types.

Note that the frozenset has no add method at all, rather than having one that raises. The mutating methods of a set simply do not exist on a frozenset, so trying to call one gives an AttributeError. The operations that do work are the read ones: membership tests, len, iteration, and the union, intersection, difference and symmetric difference operations, which all return new frozensets.

Hashing follows from immutability, and you can see both properties directly.

frozen = frozenset({1, 2})
normal = {1, 2}

print(hash(frozen) == hash(frozenset({2, 1})))   # True - hashes by contents

try:
    frozen.add(3)
except AttributeError as err:
    print("AttributeError:", err)

try:
    hash(normal)
except TypeError as err:
    print("TypeError:", err)

The first line shows that a frozenset hashes by its contents, so two frozensets holding the same elements produce the same hash. The AttributeError confirms there is no add method on a frozenset. The TypeError confirms that hashing a plain set fails, because a mutable object cannot safely be used as a key.

The reason is the same in both directions. A hash must be stable for the lifetime of the object, because a hash table computes the hash once when the object is inserted and relies on it staying the same. A mutable set can change its contents at any moment, so its hash would change and the hash table would be left inconsistent. Python therefore makes sets explicitly unhashable rather than letting you get silent corruption.

One consequence to note: because the two types hash the same way, a frozenset and a set with equal contents compare equal to each other. That is useful to know, because it means you can look a frozenset up in a dictionary keyed by frozensets, and a plain set cannot be substituted as the key.

A frozenset is the immutable counterpart of a set. It holds unique hashable elements, supports membership tests and iteration and the read-only set operations, and has no mutating methods at all. Where a set would have add, update, remove and clear, a frozenset simply does not offer them.

It is hashable, and the reason is the immutability. A hash is a fingerprint that must stay constant while the object is used as a key in a dict or a member of a set, because the hash table stores it at insertion time and trusts it afterwards. Since the contents of a frozenset can never change, its hash can never change, so it is safe. A normal set refuses to hash for exactly the same reason, and doing so would raise a TypeError rather than corrupt the table silently.

Three situations where a frozenset is the right tool. First, as a dictionary key or a member of another set — a cache keyed by a set of permissions, a map of frozenset to frozenset. Second, as a member of a class that needs hashable attributes, where a dataclass with a frozenset field is automatically usable as a key. Third, as a fixed default value in a function signature, where a frozenset communicates that the caller must not mutate it and cannot.

It also comes up for free in places you did not choose. The keys view of a dict is hashable, and it returns frozensets, because a live view must not be mutable. And frozenset is exactly what a set becomes when you put it inside another set.