Python frozendict() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Python 3.15+

Definition

In Python 3.15 and newer, frozendict() creates an immutable mapping: it stores key/value pairs like a dict, but nothing can be added, changed, or removed after it is created. It was added by PEP 814.

Because it cannot change, a frozendict whose values are all hashable can itself be hashed, so it can be a dict key or a set item, much like frozenset is to set. On older versions the name does not exist; the usual read-only substitute is types.MappingProxyType, which blocks changes but is not hashable.

frozendict is a built-in type (a class) that you call like a function. On Python 3.15+ it is always available without an import, like every other built-in. New in Python 3.15. On Python 3.14 and older, using it raises NameError: name 'frozendict' is not defined, so the examples below include a fallback. This page sticks to the basic behaviour; check the official Python 3.15 documentation for full details such as the exact method list.

Syntax

It accepts the same kinds of arguments as dict().

python
config = frozendict(host="localhost", port=8080)
config = frozendict({"a": 1, "b": 2})
config = frozendict([("a", 1), ("b", 2)])
CallWhat it does
frozendict(a=1)A read-only mapping with one key.
fd["a"]Reads a value, like a dict.
fd.get("x", 0)Reads with a default.
{fd: "label"}Uses the frozendict as a key (values must be hashable).

Reading works like a normal dict: indexing, get(), in, len(), and iterating over keys, values, and items.

Library declarations
python
frozendict(**kwargs)
frozendict(mapping, /, **kwargs)
frozendict(iterable, /, **kwargs)
# new in Python 3.15 (PEP 814)

Parameters

ParameterDescription
mapping / iterableOptional. A mapping, or an iterable of key/value pairs, as for dict().
**kwargsOptional. Extra keys given as keyword arguments.

Return Value

Return ValueDescription
frozendictA new immutable mapping (Python 3.15+).

Python Examples

Example 1 — A Read-Only Config That Works on Any Version

Use frozendict when it exists and fall back to MappingProxyType otherwise; the output is the same on both.

python
from types import MappingProxyType

try:
    make_frozen = frozendict
except NameError:  # Python 3.14 and older
    def make_frozen(data):
        return MappingProxyType(dict(data))

settings = make_frozen({"theme": "dark", "font_size": 14})
print(settings["theme"])
print(len(settings), sorted(settings))

try:
    settings["theme"] = "light"
except TypeError:
    print("read-only: item assignment raises TypeError")

How It Works

  1. Feature detection. Looking up the name frozendict raises NameError on older versions, which selects the fallback.
  2. Same reading API. Indexing, len(), and iteration behave identically for both kinds of read-only mapping.
  3. Writes are rejected. Both frozendict and MappingProxyType raise TypeError on item assignment.
  4. Copy first. The fallback wraps dict(data), a private copy, so nobody else can change the mapping behind the proxy.

Example 2 — Use a Mapping as a Dict Key

On Python 3.15+ a frozendict is the key; on older versions a frozenset of items plays the same role. Both branches print the same lines.

python
import sys

if sys.version_info >= (3, 15):
    point_a = frozendict(x=1, y=2)
    point_b = frozendict(y=2, x=1)
else:
    point_a = frozenset({"x": 1, "y": 2}.items())
    point_b = frozenset({"y": 2, "x": 1}.items())

labels = {point_a: "home"}
print(labels[point_b])
print(point_a == point_b)

How It Works

  1. Version check. sys.version_info >= (3, 15) picks the branch; the older branch never touches the name frozendict.
  2. Equal mappings, equal keys. The two frozendicts list x and y in different orders but compare equal, so they find the same dict entry.
  3. Fallback key. frozenset(d.items()) is hashable and also ignores order, so older versions behave the same.
  4. Hashable values needed. This works because 1 and 2 are hashable; a list value would make hashing fail.

Example 3 — "Change" a frozendict by Building a New One

Create an updated copy instead of modifying in place. The first line differs by version, as marked.

python
try:
    frozendict
    HAS_FROZENDICT = True
except NameError:
    HAS_FROZENDICT = False

base = {"lang": "python", "level": 1}
if HAS_FROZENDICT:
    frozen = frozendict(base)
    updated = frozendict(frozen, level=2)
    print(type(frozen).__name__)
else:
    frozen = dict(base)
    updated = dict(frozen, level=2)
    print("frozendict not available; using dict copies")

print(frozen["level"], updated["level"])
print(dict(updated))

How It Works

  1. A bare name as a probe. The statement frozendict does nothing except raise NameError when the type is missing.
  2. New object per change. frozendict(frozen, level=2) copies the pairs and overrides one key, like dict(d, key=value).
  3. Original untouched. frozen["level"] is still 1 while updated["level"] is 2.
  4. Back to a dict. dict(updated) gives a normal, mutable dict when you need one.

Frequently Asked Questions

frozendict is new in Python 3.15 (PEP 814). On 3.14 and older, the name is not defined and you get NameError.
For mappings that must not change, such as configuration or constants, and for mappings that need to be hashable, for example as dict keys or cache keys.
types.MappingProxyType(dict(data)) gives a read-only view. For a hashable key, use frozenset(data.items()) or a tuple of sorted items.
Only if all of its values are hashable. A frozendict that contains a list value cannot be hashed.
You cannot change it in place. Build a new one with the updated key, or convert it to a dict, change that, and freeze it again.

Next: frozenset()

Build an immutable, hashable set.

frozenset() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

15 people found this page helpful