Pydantic: Configuring Models with `model_config`

Why it exists

Pydantic's default validation is powerful, but real-world applications often need custom rules applied consistently across many models. Instead of repeating validation logic, model_config provides a central, declarative way to tune Pydantic's core behavior for an entire model or type.

The mental model

model_config is like a control panel for a Pydantic model. It's a dictionary of settings you attach to a model class to change how it validates, serializes, and behaves. For example, you can flip a switch to make the model immutable (frozen=True) or set a global speed limit for all string fields (str_max_length=100).

How it works

You define configuration on a Pydantic BaseModel using a class attribute named model_config, assigning it a ConfigDict object. For example, model_config = ConfigDict(frozen=True). Pydantic's core validation engine reads this dictionary when the model class is created and applies the specified rules during data parsing and validation. This same principle applies to other types, though the syntax varies slightly: Pydantic dataclasses use a config argument in the decorator, and TypeAdapter also accepts a config argument.

When to use it

Use model_config when you need to apply a consistent behavior to all instances of a model. This is ideal for setting application-wide constraints like maximum string lengths, enabling strict mode to prevent type coercion (strict=True), or making data transfer objects immutable (frozen=True) to prevent accidental mutation after validation. It's also the place to configure JSON schema generation.

When not to use it

Do not use model_config for logic that is specific to a single field. For field-specific rules, use the Field function from Pydantic (e.g., my_field: str = Field(max_length=50)). model_config is for model-wide or cross-field behaviors. Also, avoid using the deprecated class Config: subclass from Pydantic V1.

One canonical example

To create an immutable user model where strings cannot exceed 100 characters, you define it by setting the model_config attribute. The class definition would be: class User(BaseModel): model_config = ConfigDict(frozen=True, str_max_length=100); id: int; username: str. Any attempt to change a User instance's field after creation will raise an error, as will providing a username longer than 100 characters.