Pydantic v1에서 Pydantic v2로 마이그레이션하기

Pydantic v1에서 Pydantic v2로 마이그레이션하기 (Migrate from Pydantic v1 to Pydantic v2)

오래된 FastAPI 앱이 있다면 Pydantic 버전 1을 쓰고 있을 수 있어요.

FastAPI 0.100.0은 Pydantic v1 또는 v2를 모두 지원했어요. 설치된 버전을 따랐죠.

FastAPI 0.119.0은 Pydantic v2 안에서의 Pydantic v1(pydantic.v1으로)을 부분적으로 지원하기 시작했어요. v2로의 마이그레이션을 돕기 위해서였어요.

FastAPI 0.126.0은 Pydantic v1 지원을 없앴고, 얼마 동안은 pydantic.v1을 계속 지원했어요.

FastAPI 0.128.0은 pydantic.v1도 지원을 없앴어요. 그래서 최신 FastAPI 버전은 Pydantic v2를 요구해요.

경고 — Pydantic 팀은 Python 3.14부터 최신 Python 버전에서 Pydantic v1 지원을 중단했어요. 여기에는 Python 3.14 이상에서 더 이상 지원되지 않는 pydantic.v1도 포함돼요. Python의 최신 기능을 쓰고 싶다면 Pydantic v2를 쓰도록 해야 해요.

Pydantic v1을 쓰는 오래된 FastAPI 앱이 있다면, 여기서 Pydantic v2로 마이그레이션하는 방법과, 점진적 마이그레이션을 돕기 위한 FastAPI 0.119.0의 기능을 보여드릴게요.

출처: 공식문서

공식 가이드

Pydantic은 v1에서 v2로의 공식 마이그레이션 가이드를 갖고 있어요.

또한 무엇이 바뀌었는지, 검증이 어떻게 더 정확하고 엄격해졌는지, 가능한 주의 사항(caveats) 등을 포함해요.

무엇이 바뀌었는지 더 잘 이해하려면 그 가이드를 읽어 보세요.

테스트

앱에 테스트가 있고, 그 테스트를 지속적 통합(CI)에서 실행하고 있는지 확인하세요.

이렇게 하면 업그레이드를 진행하고 모든 게 여전히 예상대로 동작하는지 확인할 수 있어요.

bump-pydantic

커스터마이즈 없이 일반적인 Pydantic 모델을 쓰는 경우가 많다면, Pydantic v1에서 v2로의 마이그레이션 과정 대부분을 자동화할 수 있어요.

같은 Pydantic 팀의 bump-pydantic을 쓸 수 있어요.

이 도구는 바꿔야 하는 코드 대부분을 자동으로 바꿔주는 데 도움을 줘요.

그 후 테스트를 실행해서 모든 게 동작하는지 확인하면 돼요. 동작한다면 끝이에요. 😎

v2 안의 Pydantic v1

Pydantic v2는 Pydantic v1의 모든 것을 서브모듈 pydantic.v1로 포함해요. 하지만 이건 Python 3.13보다 위 버전에서는 더 이상 지원되지 않아요.

즉, 최신 버전의 Pydantic v2를 설치하고 예전 Pydantic v1 컴포넌트를 이 서브모듈에서 임포트해서, 예전 Pydantic v1이 설치된 것처럼 쓸 수 있어요.

from pydantic.v1 import BaseModel

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

v2 안의 Pydantic v1에 대한 FastAPI 지원

경고 — pydantic.v1 모델에 대한 이 FastAPI 지원은 FastAPI 0.119.0에서 추가됐고 FastAPI 0.128.0에서 제거됐어요. Pydantic v2로의 마이그레이션을 위한 임시 도우미로 의도됐었죠. 현재 FastAPI 버전에서는 앱에서 pydantic.v1 모델을 쓰면 에러가 발생해요. 이 섹션의 나머지 부분은 그 예전 버전들에서만 쓸 수 있었던 임시 지원을 설명해요.

FastAPI 0.119.0부터는 Pydantic v2 내부의 Pydantic v1에 대한 부분 지원도 있었어요. v2로의 마이그레이션을 돕기 위해서였죠.

그래서 Pydantic을 최신 버전 2로 업그레이드하고, 임포트를 pydantic.v1 서브모듈을 쓰도록 바꾸면, 많은 경우 그냥 동작했어요.

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

경고 — Pydantic 팀이 최신 Python 버전에서 Pydantic v1을 지원하지 않기 때문에, Python 3.14부터는 pydantic.v1을 쓰는 것도 Python 3.14 이상에서 지원되지 않는다는 점을 명심하세요.

같은 앱 안의 Pydantic v1과 v2

자신의 필드가 Pydantic v1 모델로 정의된 Pydantic v2 모델을 갖는 것(또는 그 반대)은 Pydantic이 지원하지 않아요.

❌ 지원 안 됨 — Pydantic v1 필드를 가진 Pydantic v2 모델(그 반대도).

...하지만 같은 앱 안에서 분리된 모델들, 일부는 Pydantic v1을, 일부는 Pydantic v2를 쓰는 건 할 수 있어요.

✅ 지원됨 — 같은 앱 안에 Pydantic v1 모델과 Pydantic v2 모델을 분리해서 두기.

경우에 따라 FastAPI 앱의 같은 경로 연산 안에서 Pydantic v1과 v2 모델을 모두 쓰는 것도 가능해요:

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

위 예시에서 입력 모델은 Pydantic v1 모델이고, 출력 모델(response_model=ItemV2로 정의된)은 Pydantic v2 모델이에요.

Pydantic v1 파라미터

Pydantic v1 모델과 함께 Body, Query, Form 같은 FastAPI 특화 파라미터 도구 중 일부를 써야 한다면, Pydantic v2로의 마이그레이션을 마치는 동안 fastapi.temp_pydantic_v1_params에서 임포트할 수 있어요:

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

단계적으로 마이그레이션하기

경고 — 아래에서 설명하는 같은 앱 안에서 Pydantic v1과 v2 모델을 모두 쓰는 점진적 마이그레이션은 FastAPI 0.119.0부터 0.127.x에서만 동작해요. FastAPI 0.128.0에서 제거됐고, 최신 버전은 Pydantic v2 모델을 요구해요.

팁 — 먼저 bump-pydantic을 시도해 보세요. 테스트가 통과하고 동작한다면, 한 번의 명령으로 끝난 거예요. ✨

bump-pydantic이 여러분의 사용 사례에 맞지 않는다면, 같은 앱 안에서 Pydantic v1과 v2 모델을 모두 지원하는 기능을 써서 Pydantic v2로 점진적으로 마이그레이션할 수 있어요.

먼저 Pydantic을 최신 버전 2로 업그레이드하고, 모든 모델의 임포트를 pydantic.v1을 쓰도록 바꿀 수 있어요.

그다음 모델들을 Pydantic v1에서 v2로 그룹별로, 단계적으로 마이그레이션하기 시작할 수 있어요. 🚶

더 알아보기 (Learn more)