Read-only model state
Prevent accidental reassignment of validated model attributes in configuration or value-object models.
Pydantic · Pipe
frozen
Set frozen=True to make a Pydantic model faux-immutable and generate a __hash__() method. Hashing is only possible when all attribute values are hashable.
How it works
The frozen configuration option makes a model faux-immutable: existing attributes cannot be reassigned, and Pydantic generates a __hash__() method. The resulting instance is hashable only when all its attribute values are hashable.
Syntax
model_config = ConfigDict(frozen=True)Parameters
| Name | Type | Description |
|---|---|---|
frozen | bool | Whether a model is faux-immutable and whether Pydantic generates its hash method. |
Returns
A boolean configuration value controlling model mutability and hash-method generation.
Key points
- With frozen=True, assignments to model attributes are prevented after the instance has been created.
- Pydantic generates a __hash__() method when frozen is enabled.
- A frozen instance can be used as a hashable value only when all its attributes are hashable.
- The option is disabled by default, so models are mutable unless configured otherwise.
- In Pydantic V1, the corresponding configuration used the inverse name allow_mutation.
Common mistakes
- A frozen model is not guaranteed to be hashable; every attribute value must itself be hashable.
- frozen controls attribute assignment rather than providing deep immutability for mutable values stored inside the model.
Example: A faux-immutable model
from pydantic import BaseModel, ConfigDict
class User(BaseModel):
model_config = ConfigDict(frozen=True)
name: str
user = User(name='Ada')
print(hash(user))
try:
user.name = 'Grace'
except Exception as exc:
print(type(exc).__name__)Setting frozen=True prevents attribute assignment after initialization and causes Pydantic to generate a hash method. Hashing succeeds here because the model's only field contains a hashable string.
When to use it
Hashable value objects
Use models as dictionary keys or set members when every field value is hashable.
Functional-style updates
Signal that updates should produce a new model instance instead of mutating the current one.
Interview questions
QWhat does frozen=True do?
Set model_config = ConfigDict(frozen=True) on the model. Pydantic then disallows attribute assignment and generates a __hash__() method.
Follow-up: Does frozen guarantee hashability? No: hashability still depends on all model attributes being hashable.
QIs a frozen model deeply immutable?
The model becomes faux-immutable, meaning attempts to assign to its attributes are rejected after construction. The option also requests generation of a hash method.
Follow-up: What happens if a field contains a list? The model may not be hashable because the list is unhashable, even though assignment to the field is blocked.
QWhat is the default value of frozen?
The documented default is False, so ordinary models allow attribute assignment unless frozen is enabled. The setting is the inverse of the older V1 allow_mutation option.
Follow-up: What was the V1 counterpart? allow_mutation was the inverse setting and defaulted to True.
Related
ConfigDictBaseModel__setattr____hash__allow_mutation