Migrate from Pydantic v1 to Pydantic v2

If you have an old FastAPI app, you might be using Pydantic version 1.

FastAPI version 0.100.0 had support for either Pydantic v1 or v2. It would use whichever you had installed.

FastAPI version 0.119.0 introduced partial support for Pydantic v1 from inside of Pydantic v2 (as pydantic.v1), to facilitate the migration to v2.

FastAPI 0.126.0 dropped support for Pydantic v1, while still supporting pydantic.v1 for a little while.

FastAPI 0.128.0 dropped support for pydantic.v1 as well, so the latest versions of FastAPI require Pydantic v2.

If you have an old FastAPI app with Pydantic v1, here I'll show you how to migrate it to Pydantic v2, and the features in FastAPI 0.119.0 to help you with a gradual migration.

Pydantic has an official Migration Guide from v1 to v2.

It also includes what has changed, how validations are now more correct and strict, possible caveats, etc.

You can read it to understand better what has changed.

Make sure you have tests for your app and you run them on continuous integration (CI).

This way, you can do the upgrade and make sure everything is still working as expected.

In many cases, when you use regular Pydantic models without customizations, you will be able to automate most of the process of migrating from Pydantic v1 to Pydantic v2.

You can use bump-pydantic from the same Pydantic team.

This tool will help you to automatically change most of the code that needs to be changed.

After this, you can run the tests and check if everything works. If it does, you are done. 😎

Pydantic v2 includes everything from Pydantic v1 as a submodule pydantic.v1. But this is no longer supported in versions above Python 3.13.

This means that you can install the latest version of Pydantic v2 and import and use the old Pydantic v1 components from this submodule, as if you had the old Pydantic v1 installed.

from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float

Since FastAPI 0.119.0, there's also partial support for Pydantic v1 from inside of Pydantic v2, to facilitate the migration to v2.

So, you could upgrade Pydantic to the latest version 2, and change the imports to use the pydantic.v1 submodule, and in many cases it would just work.

from fastapi import FastAPI
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item) -> Item:
    return item

It's not supported by Pydantic to have a model of Pydantic v2 with its own fields defined as Pydantic v1 models or vice versa.

graph TB
    subgraph "❌ Not Supported"
        direction TB
        subgraph V2["Pydantic v2 Model"]
            V1Field["Pydantic v1 Model"]
        end
        subgraph V1["Pydantic v1 Model"]
            V2Field["Pydantic v2 Model"]
        end
    end

    style V2 fill:#f9fff3
    style V1 fill:#fff6f0
    style V1Field fill:#fff6f0
    style V2Field fill:#f9fff3

...but you can have separate models, some using Pydantic v1 and others using Pydantic v2, in the same app.

graph TB
    subgraph "✅ Supported"
        direction TB
        subgraph V2["Pydantic v2 Model"]
            V2Field["Pydantic v2 Model"]
        end
        subgraph V1["Pydantic v1 Model"]
            V1Field["Pydantic v1 Model"]
        end
    end

    style V2 fill:#f9fff3
    style V1 fill:#fff6f0
    style V1Field fill:#fff6f0
    style V2Field fill:#f9fff3

In some cases, it's even possible to have both Pydantic v1 and v2 models in the same path operation in your FastAPI app:

from fastapi import FastAPI
from pydantic import BaseModel as BaseModelV2
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float


class ItemV2(BaseModelV2):
    name: str
    description: str | None = None
    size: float


app = FastAPI()


@app.post("/items/", response_model=ItemV2)
async def create_item(item: Item):
    return item

In this example above, the input model is a Pydantic v1 model, and the output model (defined in response_model=ItemV2) is a Pydantic v2 model.

If you need to use some of the FastAPI-specific tools for parameters like Body, Query, Form, etc. with Pydantic v1 models, you can import them from fastapi.temp_pydantic_v1_params while you finish the migration to Pydantic v2:

from typing import Annotated

from fastapi import FastAPI
from fastapi.temp_pydantic_v1_params import Body
from pydantic.v1 import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    size: float


app = FastAPI()


@app.post("/items/")
async def create_item(item: Annotated[Item, Body(embed=True)]) -> Item:
    return item

If bump-pydantic doesn't work for your use case, you can use the support for both Pydantic v1 and v2 models in the same app to do the migration to Pydantic v2 gradually.

You could first upgrade Pydantic to use the latest version 2, and change the imports to use pydantic.v1 for all your models.

Then, you can start migrating your models from Pydantic v1 to v2 in groups, in gradual steps. 🚶