Skip to content

Standard Library Types

Pydantic supports many common types from the Python standard library. If you need stricter processing see Strict types, including if you need to constrain the values allowed (e.g. to require a positive int).

Type Description
None, type(None), or Literal[None] Equivalent according to PEP 484. Allows only None value.
bool See Booleans for details on how bools are validated and what values are permitted.
int Pydantic uses int(v) to coerce types to an int. See Number Types for more details. See the Data Conversion warning on loss of information during data conversion.
float float(v) is used to coerce values to floats. See Number Types for more details.
str Strings are accepted as-is. int, float, and Decimal are coerced using str(v). bytes and bytearray are converted using v.decode(). Enums inheriting from str are converted using v.value. All other types cause an error. See String Types for more details.
bytes bytes are accepted as-is. bytearray is converted using bytes(v). str are converted using v.encode(). int, float, and Decimal are coerced using str(v).encode(). See ByteSize for more details.
list Allows list, tuple, set, frozenset, deque, or generators and casts to a list. See typing.List for sub-type constraints.
tuple Allows list, tuple, set, frozenset, deque, or generators and casts to a tuple. See typing.Tuple for sub-type constraints.
dict dict(v) is used to attempt to convert a dictionary. See typing.Dict for sub-type constraints.
set Allows list, tuple, set, frozenset, deque, or generators and casts to a set. See typing.Set for sub-type constraints.
frozenset Allows list, tuple, set, frozenset, deque, or generators and casts to a frozen set. See typing.FrozenSet for sub-type constraints.
deque Allows list, tuple, set, frozenset, deque, or generators and casts to a deque. See typing.Deque for sub-type constraints.
datetime.date See Datetime Types for more detail on parsing and validation.
datetime.time See Datetime Types for more detail on parsing and validation.
datetime.datetime See Datetime Types for more detail on parsing and validation.
datetime.timedelta See Datetime Types for more detail on parsing and validation.
typing.Any Allows any value including None, thus an Any field is optional.
typing.Annotated Allows wrapping another type with arbitrary metadata, as per PEP-593. The Annotated hint may contain a single call to the Field function, but otherwise the additional metadata is ignored and the root type is used.
typing.TypeVar Constrains the values allowed based on constraints or bound, see TypeVar.
typing.Union See Unions for more detail on parsing and validation.
typing.Optional Optional[x] is simply short hand for Union[x, None]. See Unions for more detail on parsing and validation and Required Fields for details about required fields that can receive None as a value.
typing.List See Lists and Tuples for more detail on parsing and validation.
typing.Tuple See Lists and Tuples for more detail on parsing and validation.
Subclass of typing.NamedTuple Same as tuple, but instantiates with the given namedtuple and validates fields since they are annotated. See Lists and Tuples for more detail.
Subclass of collections.namedtuple Same as subclass of typing.NamedTuple, but all fields will have type Any since they are not annotated. See Lists and Tuples for more detail.
typing.Dict See Dicts and mapping for more detail on parsing and validation.
Subclass of typing.TypedDict Same as dict, but Pydantic will validate the dictionary since keys are annotated.
typing.Set See Sets and frozenset for more detail on parsing and validation.
typing.FrozenSet See Sets and frozenset for more detail on parsing and validation.
typing.Deque See Sequence, Iterable & Iterator for more detail on parsing and validation.
typing.Sequence See Sequence, Iterable & Iterator for more detail on parsing and validation.
typing.Iterable This is reserved for iterables that shouldn't be consumed. See Sequence, Iterable & Iterator for more detail on parsing and validation.
typing.Type See Type and Typevars for more detail on parsing and validation.
typing.Callable See Callables for more detail on parsing and validation.
typing.Pattern Will cause the input value to be passed to re.compile(v) to create a regular expression pattern.
ipaddress.IPv4Address Simply uses the type itself for validation by passing the value to IPv4Address(v). See URLs for other custom IP address types.
ipaddress.IPv4Interface Simply uses the type itself for validation by passing the value to IPv4Address(v). See URLs for other custom IP address types.
ipaddress.IPv4Network Simply uses the type itself for validation by passing the value to IPv4Network(v). See URLs for other custom IP address types.
ipaddress.IPv6Address Simply uses the type itself for validation by passing the value to IPv6Address(v). See URLs for other custom IP address types.
ipaddress.IPv6Interface Simply uses the type itself for validation by passing the value to IPv6Interface(v). See URLs for other custom IP address types.
ipaddress.IPv6Network Simply uses the type itself for validation by passing the value to IPv6Network(v). See URLs for other custom IP address types.
enum.Enum Checks that the value is a valid Enum instance. See Enums and Choices for more details.
Subclass of enum.Enum Checks that the value is a valid member of the enum. See Enums and Choices for more details.
enum.IntEnum Checks that the value is a valid IntEnum instance. See Enums and Choices for more details.
Subclass of enum.IntEnum Checks that the value is a valid member of the integer enum. See Enums and Choices for more details.
decimal.Decimal Pydantic attempts to convert the value to a string, then passes the string to Decimal(v). See Number Types for more details.
pathlib.Path Simply uses the type itself for validation by passing the value to Path(v). See File Types for other, more strict path types.
uuid.UUID Strings and bytes (converted to strings) are passed to UUID(v), with a fallback to UUID(bytes=v) for bytes and bytearray. See UUIDs for other, more strict UUID types.
ByteSize Converts a bytes string with units to bytes. See ByteSize for more details.

Type conversion

During validation, Pydantic can coerce data into expected types.

There are two modes of coercion: strict and lax. See Conversion Table for more details on how Pydantic converts data in both strict and lax modes.

See Strict mode and Strict Types for details on enabling strict coercion.

Literal type

Note

This is a new feature of the Python standard library as of Python 3.8; prior to Python 3.8, it requires the typing-extensions package.

Pydantic supports the use of typing.Literal (or typing_extensions.Literal prior to Python 3.8) as a lightweight way to specify that a field may accept only specific literal values:

from typing import Literal

from pydantic import BaseModel, ValidationError


class Pie(BaseModel):
    flavor: Literal['apple', 'pumpkin']


Pie(flavor='apple')
Pie(flavor='pumpkin')
try:
    Pie(flavor='cherry')
except ValidationError as e:
    print(str(e))
    """
    1 validation error for Pie
    flavor
      Input should be 'apple' or 'pumpkin' [type=literal_error, input_value='cherry', input_type=str]
    """

One benefit of this field type is that it can be used to check for equality with one or more specific values without needing to declare custom validators:

from typing import ClassVar, List, Literal, Union

from pydantic import BaseModel, ValidationError


class Cake(BaseModel):
    kind: Literal['cake']
    required_utensils: ClassVar[List[str]] = ['fork', 'knife']


class IceCream(BaseModel):
    kind: Literal['icecream']
    required_utensils: ClassVar[List[str]] = ['spoon']


class Meal(BaseModel):
    dessert: Union[Cake, IceCream]


print(type(Meal(dessert={'kind': 'cake'}).dessert).__name__)
#> Cake
print(type(Meal(dessert={'kind': 'icecream'}).dessert).__name__)
#> IceCream
try:
    Meal(dessert={'kind': 'pie'})
except ValidationError as e:
    print(str(e))
    """
    2 validation errors for Meal
    dessert.Cake.kind
      Input should be 'cake' [type=literal_error, input_value='pie', input_type=str]
    dessert.IceCream.kind
      Input should be 'icecream' [type=literal_error, input_value='pie', input_type=str]
    """

With proper ordering in an annotated Union, you can use this to parse types of decreasing specificity:

from typing import Literal, Optional, Union

from pydantic import BaseModel


class Dessert(BaseModel):
    kind: str


class Pie(Dessert):
    kind: Literal['pie']
    flavor: Optional[str]


class ApplePie(Pie):
    flavor: Literal['apple']


class PumpkinPie(Pie):
    flavor: Literal['pumpkin']


class Meal(BaseModel):
    dessert: Union[ApplePie, PumpkinPie, Pie, Dessert]


print(type(Meal(dessert={'kind': 'pie', 'flavor': 'apple'}).dessert).__name__)
#> ApplePie
print(type(Meal(dessert={'kind': 'pie', 'flavor': 'pumpkin'}).dessert).__name__)
#> PumpkinPie
print(type(Meal(dessert={'kind': 'pie'}).dessert).__name__)
#> Dessert
print(type(Meal(dessert={'kind': 'cake'}).dessert).__name__)
#> Dessert