Skip to main content

Deprecations and Compatibility

FastAPI manages the evolution of its API and underlying dependencies through a combination of strict error enforcement for breaking changes and visible warnings for gradual deprecations. This approach ensures that developers are alerted to necessary migrations while maintaining a clear path forward as the framework adopts newer standards like Pydantic V2 and OpenAPI 3.1.0.

Pydantic V1 Migration and Enforcement​

With the transition to Pydantic V2, FastAPI has moved away from supporting Pydantic V1 models in core components. This is not a soft deprecation but a strict requirement enforced at runtime. If a Pydantic V1 model is used where a V2 model is expected, FastAPI raises a PydanticV1NotSupportedError.

Field Creation and Route Signatures​

The primary enforcement point is during the creation of model fields for route parameters and response models. In fastapi/utils.py, the create_model_field function checks the type annotation of every parameter. If it detects a Pydantic V1 model (via the internal annotation_is_pydantic_v1 check), it halts execution:

# From fastapi/utils.py
def create_model_field(
    name: str,
    type_: Any,
    # ...
) -> ModelField:
    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}."
        )
    # ...

JSON Encoding​

FastAPI also prevents Pydantic V1 models from being processed by its encoding utilities. In fastapi/encoders.py, the jsonable_encoder function explicitly checks for V1 model instances. This prevents accidental serialization of legacy models that might not behave correctly with the V2-based encoding logic:

# From fastapi/encoders.py
if is_pydantic_v1_model_instance(obj):
    raise PydanticV1NotSupportedError(
        "pydantic.v1 models are no longer supported by FastAPI."
        f" Please update the model {obj!r}."
    )

Communicating Changes with FastAPIDeprecationWarning​

For features that are being phased out but do not yet cause a hard failure, FastAPI uses FastAPIDeprecationWarning. This class inherits from UserWarning rather than the standard DeprecationWarning.

The design choice to use UserWarning is intentional: by default, Python silences DeprecationWarning in many environments, which can lead to developers missing critical information about upcoming breaking changes. By using a custom UserWarning subclass, FastAPI ensures that these messages are visible in the console during development and testing.

Common Deprecated Parameters​

Several parameters in Query, Path, Body, and Header have been updated to align with Pydantic V2 and OpenAPI 3.1.0. FastAPI emits a FastAPIDeprecationWarning when the legacy versions are used:

  • regex vs pattern: The regex parameter is deprecated in favor of pattern.
  • example vs examples: The single example parameter is deprecated in favor of the plural examples (or openapi_examples), following the OpenAPI 3.1.0 specification.

In fastapi/params.py, these deprecations are implemented by checking for the presence of the old arguments in the __init__ method:

# From fastapi/params.py
if example is not _Unset:
    warnings.warn(
        "`example` has been deprecated, please use `examples` instead",
        category=FastAPIDeprecationWarning,
        stacklevel=4,
    )

if regex is not None:
    warnings.warn(
        "`regex` has been deprecated, please use `pattern` instead",
        category=FastAPIDeprecationWarning,
        stacklevel=4,
    )

Deprecated Response Classes​

Certain specialized response classes, such as ORJSONResponse and UJSONResponse, are now deprecated because FastAPI (via Pydantic V2) can now serialize data directly to JSON more efficiently. These classes are marked with the @deprecated decorator, which triggers a FastAPIDeprecationWarning upon instantiation:

# From fastapi/responses.py
@deprecated(
    "ORJSONResponse is deprecated, FastAPI now serializes data directly to JSON...",
    category=FastAPIDeprecationWarning,
    stacklevel=2,
)
class ORJSONResponse(JSONResponse):
    ...

Managing Warnings in Development​

Because FastAPIDeprecationWarning is a subclass of UserWarning, it can be managed using Python's standard warnings filter. This is particularly useful in test suites where you may want to treat these warnings as errors to ensure your codebase remains up-to-date.

For example, you can use pytest to verify that a deprecated feature is being used:

import pytest
from fastapi.exceptions import FastAPIDeprecationWarning
from fastapi.responses import ORJSONResponse

def test_deprecated_orjson():
    with pytest.warns(FastAPIDeprecationWarning, match="ORJSONResponse is deprecated"):
        ORJSONResponse(content={"message": "hello"})

Conversely, if you are in the middle of a migration and need to temporarily silence these warnings, you can filter them by their specific class:

import warnings
from fastapi.exceptions import FastAPIDeprecationWarning

# Silence FastAPI deprecation warnings
warnings.filterwarnings("ignore", category=FastAPIDeprecationWarning)