# Configuration

The behaviour of Pydantic can be controlled via a variety of configuration values, documented
on the `ConfigDict` class. This page describes how configuration can be
specified for Pydantic's supported types.

## Configuration on Pydantic models

On Pydantic models, configuration can be specified in two ways:

- Using the [`model_config`](/guides/pydantic-base-model) class attribute:

  ```python
  from pydantic import BaseModel, ConfigDict, ValidationError


  class Model(BaseModel):
      model_config = ConfigDict(str_max_length=5)

      v: str


  try:
      m = Model(v='abcdef')
  except ValidationError as e:
      print(e)
      """
      1 validation error for Model
      v
        String should have at most 5 characters [type=string_too_long, input_value='abcdef', input_type=str]
      """
  ```

  1. A plain dictionary (i.e. `{'str_max_length': 5}`) can also be used.

  !!! note
  In Pydantic V1, the `Config` class was used. This is still supported, but **deprecated**.

- Using class arguments:

  ```python
  from pydantic import BaseModel


  class Model(BaseModel, frozen=True):
      a: str
  ```

  Unlike the [`model_config`](/guides/pydantic-base-model) class attribute,
  static type checkers will recognize class arguments. For `frozen`, any instance
  mutation will be flagged as a type checking error.

## Configuration on Pydantic dataclasses

[Pydantic dataclasses](/guides/concepts-dataclasses) also support configuration (read more in the
[dedicated section](/guides/concepts-dataclasses#dataclass-config)).

```python
from pydantic import ConfigDict, ValidationError
from pydantic.dataclasses import dataclass


@dataclass(config=ConfigDict(str_max_length=10, validate_assignment=True))
class User:
    name: str


user = User(name='John Doe')
try:
    user.name = 'x' * 20
except ValidationError as e:
    print(e)
    """
    1 validation error for User
    name
      String should have at most 10 characters [type=string_too_long, input_value='xxxxxxxxxxxxxxxxxxxx', input_type=str]
    """
```

## Configuration on `TypeAdapter`

[Type adapters](/guides/concepts-type-adapter) (using the [`TypeAdapter`](/guides/pydantic-type-adapter) class) support configuration,
by providing the `config` argument.

```python
from pydantic import ConfigDict, TypeAdapter

ta = TypeAdapter(list[str], config=ConfigDict(coerce_numbers_to_str=True))

print(ta.validate_python([1, 2]))
#> ['1', '2']
```

Configuration can't be provided if the type adapter directly wraps a type that support it, and a
[usage error](/guides/error-messages-usage-errors) is raised in this case.
The [configuration propagation](#configuration-propagation) rules also apply.

## Configuration on other supported types

If you are using standard library dataclasses or `TypedDict` classes,
the configuration can be set in two ways:

- Using the `__pydantic_config__` class attribute:

  ```python
  from dataclasses import dataclass

  from pydantic import ConfigDict


  @dataclass
  class User:
      __pydantic_config__ = ConfigDict(strict=True)

      id: int
      name: str = 'John Doe'
  ```

- Using the [`@with_config`](/guides/pydantic-config) decorator (this avoids static type checking errors with
  `TypedDict`):

  ```python
  from typing_extensions import TypedDict

  from pydantic import ConfigDict, with_config


  @with_config(ConfigDict(str_to_lower=True))
  class Model(TypedDict):
      x: str
  ```

## Configuration on the `@validate_call` decorator

The [`@validate_call`](/guides/concepts-validation-decorator) also supports setting custom configuration. See the
[dedicated section](/guides/concepts-validation-decorator#custom-configuration) for more details.

## Change behaviour globally

If you wish to change the behaviour of Pydantic globally, you can create your own custom parent class
with a custom configuration, as the configuration is inherited:

```python
from pydantic import BaseModel, ConfigDict


class Parent(BaseModel):
    model_config = ConfigDict(extra='allow')


class Model(Parent):
    x: str


m = Model(x='foo', y='bar')
print(m.model_dump())
#> {'x': 'foo', 'y': 'bar'}
```

If you provide configuration to the subclasses, it will be _merged_ with the parent configuration:

```python
from pydantic import BaseModel, ConfigDict


class Parent(BaseModel):
    model_config = ConfigDict(extra='allow', str_to_lower=False)


class Model(Parent):
    model_config = ConfigDict(str_to_lower=True)

    x: str


m = Model(x='FOO', y='bar')
print(m.model_dump())
#> {'x': 'foo', 'y': 'bar'}
print(Model.model_config)
#> {'extra': 'allow', 'str_to_lower': True}
```

:::callout{intent="warning"}
If your model inherits from multiple bases, Pydantic currently _doesn't_ follow the
[MRO]. For more details, see [this issue](https://github.com/pydantic/pydantic/issues/9992).

[MRO]: https://docs.python.org/3/glossary.html#term-method-resolution-order
:::

## Plugin settings

The `plugin_settings` configuration value passes options to
Pydantic plugins (code that hooks into validation, usually for tooling that observes it rather than for
changing validation behaviour). Its value is a dictionary keyed by plugin name, so a given plugin reads
only its own entry.

The main plugin in use today is [Logfire](/guides/integrations-logfire)'s, which records validations for
observability. You can tune what it records per model, for instance recording only failures for one
particular model:

```python
from pydantic import BaseModel


class User(BaseModel, plugin_settings={'logfire': {'record': 'failure'}}):
    name: str
    email: str
```

## Configuration propagation

When using types that support configuration as field annotations, configuration may not be propagated:

- For Pydantic models and dataclasses, configuration will _not_ be propagated, each model has its own
  "configuration boundary":

  ```python
  from pydantic import BaseModel, ConfigDict


  class User(BaseModel):
      name: str


  class Parent(BaseModel):
      user: User

      model_config = ConfigDict(str_to_lower=True)


  print(Parent(user={'name': 'JOHN'}))
  #> user=User(name='JOHN')
  ```

- For stdlib types (dataclasses and typed dictionaries), configuration will be propagated, unless
  the type has its own configuration set:

  ```python
  from dataclasses import dataclass

  from pydantic import BaseModel, ConfigDict, with_config


  @dataclass
  class UserWithoutConfig:
      name: str


  @dataclass
  @with_config(str_to_lower=False)
  class UserWithConfig:
      name: str


  class Parent(BaseModel):
      user_1: UserWithoutConfig
      user_2: UserWithConfig

      model_config = ConfigDict(str_to_lower=True)


  print(Parent(user_1={'name': 'JOHN'}, user_2={'name': 'JOHN'}))
  #> user_1=UserWithoutConfig(name='john') user_2=UserWithConfig(name='JOHN')
  ```

## Related pages

- [API Documentation](./api-documentation-index.md)
- [Concepts](./concepts-index.md)
- [Dev Tools](./dev-tools-index.md)
- [Error Messages](./error-messages-index.md)
- [Examples](./examples-index.md)
- [Integrations](./integrations-index.md)
- [Internals](./internals-index.md)
- [Production Tools](./production-tools-index.md)
- [Pydantic](./pydantic-index.md)
- [Pydantic Core](./pydantic-core-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.