Pydantic compatibility

Purpose

fastapi/_compat/ is the boundary that isolates the rest of the framework from Pydantic-internal API. Pydantic's API has shifted over major versions; FastAPI keeps the rest of its source agnostic by routing all Pydantic-internal calls through this module.

Directory layout

fastapi/_compat/
├── __init__.py    # Re-exports a stable surface
├── shared.py      # Helpers usable across versions: annotation predicates, sequence detection
└── v2.py          # Pydantic v2 implementations (the active backend)

Pydantic v1 support has been removed. There used to be a v1.py companion to v2.py. Today, attempting to use a Pydantic v1 model raises PydanticV1NotSupportedError from fastapi/utils.py:create_model_field.

Public surface (fastapi/_compat/__init__.py)

The package re-exports about two dozen names. Everything in the rest of the framework imports from fastapi._compat, never from fastapi._compat.v2 or pydantic._internal.

Name	Purpose
ModelField	Wrapper around pydantic.fields.FieldInfo plus serialization helpers. The unit FastAPI builds dependants out of.
Undefined, RequiredParam	Pydantic sentinel re-exports.
Url	Pydantic URL type used in encoders.
PydanticSchemaGenerationError	Re-export — caught when a return annotation cannot be turned into a model field, then re-raised as FastAPIError with a hint.
copy_field_info, create_body_model, evaluate_forwardref	Implementation hooks for parameter analysis.
get_definitions, get_model_name_map, get_schema_from_model_field, get_flat_models_from_fields, get_cached_model_fields	OpenAPI schema-generation helpers.
is_scalar_field, serialize_sequence_value, with_info_plain_validator_function	Misc helpers used in routing and encoders.
field_annotation_is_scalar, field_annotation_is_sequence, field_annotation_is_scalar_sequence, value_is_sequence, sequence_types	Annotation predicates used by analyze_param.
is_uploadfile_or_nonable_uploadfile_annotation, is_uploadfile_sequence_annotation	Detect UploadFile parameters during parameter analysis.
is_bytes_or_nonable_bytes_annotation, is_bytes_sequence_annotation	Detect bytes-shaped parameters.
annotation_is_pydantic_v1, is_pydantic_v1_model_instance	Detection for the v1-not-supported error path.
lenient_issubclass, get_missing_field_error	Small utilities.
PYDANTIC_VERSION_MINOR_TUPLE	The active Pydantic version, exposed for code that gates on it.

How ModelField is used

get_dependant walks an endpoint's signature and builds a ModelField per parameter. The dependant resolver later calls ModelField.validate(value, {}, loc=...) to apply Pydantic validation. serialize_response calls ModelField.serialize to write JSON bytes via Pydantic's optimised path. When OpenAPI generation runs, get_schema_from_model_field and get_definitions produce JSON Schema for each field. The ModelField API is FastAPI's, not Pydantic's — _compat/v2.py adapts it to whatever Pydantic provides.

Why the v1 path is gone

Pydantic 1 and 2 use incompatible field metadata, validator semantics, and JSON-Schema generators. Carrying both indefinitely added complexity to every signature-analysis path. The decision to drop v1 simplified get_dependant, get_schema_from_model_field, and serialize_response. The runtime check in create_model_field produces a clear error rather than a confusing failure deep in Pydantic.

def create_model_field(name, type_, ...):
    if annotation_is_pydantic_v1(type_):
        raise PydanticV1NotSupportedError(
            "pydantic.v1 models are no longer supported by FastAPI. "
            f"Please update the response model {type_!r}."
        )
    ...

Integration points

• Down to Pydantic — every Pydantic-internal call in the framework lives in _compat/v2.py.
• Up to the rest of fastapi/ — dependencies/utils.py, routing.py, openapi/utils.py, encoders.py, and params.py all import from fastapi._compat.

Entry points for modification

• Pydantic upgrade: most edits will land in fastapi/_compat/v2.py. Keep the names in fastapi/_compat/__init__.py stable.
• New helper used in two or more places: add it to _compat/shared.py (cross-version) or _compat/v2.py, then re-export from __init__.py.
• Probing Pydantic feature support: gate on PYDANTIC_VERSION_MINOR_TUPLE (re-exported from shared.py).