Migrar de Pydantic v1 a Pydantic v2¶
Si tienes una aplicación FastAPI antigua, puede que estés usando Pydantic versión 1.
La versión 0.100.0 de FastAPI tenía soporte tanto para Pydantic v1 como para v2. Usaría la que tuvieras instalada.
La versión 0.119.0 de FastAPI introdujo soporte parcial para Pydantic v1 desde dentro de Pydantic v2 (como pydantic.v1), para facilitar la migración a v2.
FastAPI 0.126.0 eliminó el soporte para Pydantic v1, aunque siguió soportando pydantic.v1 por un tiempo más.
FastAPI 0.128.0 eliminó también el soporte para pydantic.v1, por lo que las últimas versiones de FastAPI requieren Pydantic v2.
Aviso
El equipo de Pydantic dejó de soportar Pydantic v1 para las últimas versiones de Python, comenzando con Python 3.14.
Esto incluye pydantic.v1, que ya no es soportado en Python 3.14 y superior.
Si quieres usar las últimas características de Python, necesitarás asegurarte de usar Pydantic v2.
Si tienes una aplicación FastAPI antigua con Pydantic v1, aquí te mostraré cómo migrarla a Pydantic v2, y las características en FastAPI 0.119.0 para ayudarte con una migración gradual.
Guía Oficial¶
Pydantic tiene una Guía de Migración oficial de v1 a v2.
También incluye qué ha cambiado, cómo las validaciones son ahora más correctas y estrictas, posibles advertencias, etc.
Puedes leerla para entender mejor qué ha cambiado.
Pruebas¶
Asegúrate de tener pruebas para tu aplicación y ejecutarlas en integración continua (CI).
De esta manera, puedes hacer la actualización y asegurarte de que todo sigue funcionando como se espera.
bump-pydantic¶
En muchos casos, cuando usas modelos de Pydantic regulares sin personalizaciones, podrás automatizar la mayor parte del proceso de migración de Pydantic v1 a Pydantic v2.
Puedes usar bump-pydantic del mismo equipo de Pydantic.
Esta herramienta te ayudará a cambiar automáticamente la mayor parte del código que necesita ser cambiado.
Después de esto, puedes ejecutar las pruebas y verificar si todo funciona. Si funciona, has terminado. 😎
Pydantic v1 en v2¶
Pydantic v2 incluye todo de Pydantic v1 como un submódulo pydantic.v1. Pero esto ya no es soportado en versiones superiores a Python 3.13.
Esto significa que puedes instalar la última versión de Pydantic v2 e importar y usar los componentes antiguos de Pydantic v1 desde este submódulo, como si tuvieras el antiguo Pydantic v1 instalado.
from pydantic.v1 import BaseModel
class Item(BaseModel):
name: str
description: str | None = None
size: float
Soporte de FastAPI para Pydantic v1 en v2¶
Aviso
Este soporte de FastAPI para modelos pydantic.v1 fue añadido en FastAPI 0.119.0 y eliminado en FastAPI 0.128.0. Estaba pensado como una ayuda temporal para la migración a Pydantic v2.
En las versiones actuales de FastAPI, usar un modelo pydantic.v1 en tu aplicación generará un error.
El resto de esta sección describe el soporte temporal disponible solo en esas versiones anteriores.
Desde FastAPI 0.119.0, también hay soporte parcial para Pydantic v1 desde dentro de Pydantic v2, para facilitar la migración a v2.
Así que podrías actualizar Pydantic a la última versión 2, y cambiar los imports para usar el submódulo pydantic.v1, y en muchos casos simplemente funcionaría.
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
Aviso
Ten en cuenta que como el equipo de Pydantic ya no soporta Pydantic v1 en las versiones recientes de Python, comenzando con Python 3.14, usar pydantic.v1 tampoco es soportado en Python 3.14 y superior.
Pydantic v1 y v2 en la misma aplicación¶
No es soportado por Pydantic tener un modelo de Pydantic v2 con sus propios campos definidos como modelos de Pydantic v1 o viceversa.
...pero puedes tener modelos separados, algunos usando Pydantic v1 y otros usando Pydantic v2, en la misma aplicación.
En algunos casos, incluso es posible tener modelos de Pydantic v1 y v2 en la misma path operation en tu aplicación FastAPI:
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
En el ejemplo anterior, el modelo de entrada es un modelo de Pydantic v1, y el modelo de salida (definido en response_model=ItemV2) es un modelo de Pydantic v2.
Parámetros de Pydantic v1¶
Si necesitas usar algunas de las herramientas específicas de FastAPI para parámetros como Body, Query, Form, etc. con modelos de Pydantic v1, puedes importarlas desde fastapi.temp_pydantic_v1_params mientras terminas la migración a 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
Migrar por pasos¶
Aviso
La migración gradual usando modelos de Pydantic v1 y v2 en la misma aplicación descrita abajo solo funciona en FastAPI 0.119.0 hasta 0.127.x. Fue eliminada en FastAPI 0.128.0, las últimas versiones requieren modelos de Pydantic v2.
Consejo
Primero prueba con bump-pydantic, si tus pruebas pasan y funciona, entonces has terminado con un solo comando. ✨
Si bump-pydantic no funciona para tu caso de uso, puedes usar el soporte para modelos de Pydantic v1 y v2 en la misma aplicación para hacer la migración a Pydantic v2 gradualmente.
Podrías primero actualizar Pydantic para usar la última versión 2, y cambiar los imports para usar pydantic.v1 para todos tus modelos.
Luego, puedes empezar a migrar tus modelos de Pydantic v1 a v2 en grupos, en pasos graduales. 🚶