Skip to content

Mypy

Pydantic works well with mypy right out of the box.

However, Pydantic also ships with a mypy plugin that adds a number of important pydantic-specific features to mypy that improve its ability to type-check your code.

For example, consider the following script:

from datetime import datetime
from typing import List, Optional

from pydantic import BaseModel


class Model(BaseModel):
    age: int
    first_name = 'John'
    last_name: Optional[str] = None
    signup_ts: Optional[datetime] = None
    list_of_ints: List[int]


m = Model(age=42, list_of_ints=[1, '2', b'3'])
print(m.middle_name)  # not a model field!
Model()  # will raise a validation error for age and list_of_ints

Without any special configuration, mypy does not catch the missing model field annotation and warns about the list_of_ints argument which Pydantic parses correctly:

test.py:15: error: List item 1 has incompatible type "str"; expected "int"  [list-item]
test.py:15: error: List item 2 has incompatible type "bytes"; expected "int"  [list-item]
test.py:16: error: "Model" has no attribute "middle_name"  [attr-defined]
test.py:17: error: Missing named argument "age" for "Model"  [call-arg]
test.py:17: error: Missing named argument "list_of_ints" for "Model"  [call-arg]

But with the plugin enabled, it gives the correct error: 

9: error: Untyped fields disallowed  [pydantic-field]
16: error: "Model" has no attribute "middle_name"  [attr-defined]
17: error: Missing named argument "age" for "Model"  [call-arg]
17: error: Missing named argument "list_of_ints" for "Model"  [call-arg]

With the pydantic mypy plugin, you can fearlessly refactor your models knowing mypy will catch any mistakes if your field names or types change.

There are other benefits too! See below for more details.

Using mypy without the plugin

You can run your code through mypy with:

mypy \
  --ignore-missing-imports \
  --follow-imports=skip \
  --strict-optional \
  pydantic_mypy_test.py

Strict Optional

For your code to pass with --strict-optional, you need to use Optional[] or an alias of Optional[] for all fields with None as the default. (This is standard with mypy.)

Other Pydantic interfaces

Pydantic dataclasses and the validate_call decorator should also work well with mypy.

Mypy Plugin Capabilities

Generate a signature for Model.__init__

  • Any required fields that don't have dynamically-determined aliases will be included as required keyword arguments.
  • If Config.populate_by_name=True, the generated signature will use the field names, rather than aliases.
  • If Config.extra='forbid' and you don't make use of dynamically-determined aliases, the generated signature will not allow unexpected inputs.
  • Optional: If the init_forbid_extra plugin setting is set to True, unexpected inputs to __init__ will raise errors even if Config.extra is not 'forbid'.
  • Optional: If the init_typed plugin setting is set to True, the generated signature will use the types of the model fields (otherwise they will be annotated as Any to allow parsing).

Generate a typed signature for Model.model_construct

  • The model_construct method is an alternative to __init__ when input data is known to be valid and should not be parsed. Because this method performs no runtime validation, static checking is important to detect errors.

Respect Config.frozen

  • If Config.frozen is True, you'll get a mypy error if you try to change the value of a model field; cf. faux immutability.

Generate a signature for dataclasses

Respect the type of the Field's default and default_factory

  • Field with both a default and a default_factory will result in an error during static checking.
  • The type of the default and default_factory value must be compatible with the one of the field.

Warn about the use of untyped fields

  • You'll get a mypy error any time you assign a public attribute on a model without annotating its type
  • If your goal is to set a ClassVar, you should explicitly annotate the field using typing.ClassVar

Optional Capabilities:

Prevent the use of required dynamic aliases

  • If the warn_required_dynamic_aliases plugin setting is set to True, you'll get a mypy error any time you use a dynamically-determined alias or alias generator on a model with Config.populate_by_name=False.
  • This is important because if such aliases are present, mypy cannot properly type check calls to __init__. In this case, it will default to treating all arguments as optional.

Enabling the Plugin

To enable the plugin, just add pydantic.mypy to the list of plugins in your mypy config file (this could be mypy.ini, pyproject.toml, or setup.cfg).

To get started, all you need to do is create a mypy.ini file with following contents: 

[mypy]
plugins = pydantic.mypy

The plugin is compatible with mypy versions >=0.930.

See the plugin configuration docs for more details.

Configuring the Plugin

To change the values of the plugin settings, create a section in your mypy config file called [pydantic-mypy], and add any key-value pairs for settings you want to override.

A mypy.ini file with all plugin strictness flags enabled (and some other mypy strictness flags, too) might look like:

[mypy]
plugins = pydantic.mypy

follow_imports = silent
warn_redundant_casts = True
warn_unused_ignores = True
disallow_any_generics = True
check_untyped_defs = True
no_implicit_reexport = True

# for strict mypy: (this is the tricky one :-))
disallow_untyped_defs = True

[pydantic-mypy]
init_forbid_extra = True
init_typed = True
warn_required_dynamic_aliases = True

As of mypy>=0.900, mypy config may also be included in the pyproject.toml file rather than mypy.ini. The same configuration as above would be:

[tool.mypy]
plugins = [
  "pydantic.mypy"
]

follow_imports = "silent"
warn_redundant_casts = true
warn_unused_ignores = true
disallow_any_generics = true
check_untyped_defs = true
no_implicit_reexport = true

# for strict mypy: (this is the tricky one :-))
disallow_untyped_defs = true

[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true