建立 2026-10-11 更新 2026-10-11

V1 遷移到 V2

Pydantic V2 於 2023 年發布，核心以 Rust 重寫，速度大幅提升，但許多 API 名稱也跟著改變。網路上仍有大量 V1 時代的教學與程式碼，本頁提供 V1 與 V2 的 API 對照表，並介紹官方自動遷移工具 bump-pydantic，幫你看懂舊程式並完成升級。

V1 和 V2 的 API 對照

V1 寫法	V2 寫法
`model.dict()`	`model.model_dump()`
`model.json()`	`model.model_dump_json()`
`Model.parse_obj(data)`	`Model.model_validate(data)`
`Model.parse_raw(s)`	`Model.model_validate_json(s)`
`model.copy(update=...)`	`model.model_copy(update=...)`
`Model.schema()`	`Model.model_json_schema()`
`Model.__fields__`	`Model.model_fields`
`@validator("x")`	`@field_validator("x")`
`@validator("x", pre=True)`	`@field_validator("x", mode="before")`
`@root_validator`	`@model_validator(mode="after")` 或 `mode="before"`
`class Config:`	`model_config = ConfigDict(...)`
`orm_mode = True`	`from_attributes=True`
`allow_mutation = False`	`frozen=True`
`from pydantic import BaseSettings`	`from pydantic_settings import BaseSettings`（獨立套件）
`parse_obj_as(list[int], data)`	`TypeAdapter(list[int]).validate_python(data)`
`Optional[int]`（自動預設 `None`）	`int \\| None = None`（必須明確寫預設值）

Optional 不再自動有預設值：V1 中 x: Optional[int] 是選填；V2 中它是「必填，但可以是 None」。要選填必須寫 x: int | None = None。
數字不會自動轉成字串：V1 會把 123 轉成 "123" 給 str 欄位；V2 會報錯。
float 轉 int 更嚴格：3.5 傳給 int 欄位會報錯，只接受沒有小數部分的值（例如 3.0）。
驗證器必須是 @classmethod：@field_validator 下方要加 @classmethod。

官方提供 bump-pydantic，會自動改寫大部分 API 名稱：

uvx bump-pydantic my_package/

執行後務必跑一次測試，並人工檢查上一節的行為差異，工具無法判斷你的程式是否依賴舊行為。

可以。V2 內附一份 V1 的相容版本，大型專案可以分階段遷移：

from pydantic.v1 import BaseModel as BaseModelV1

這只是過渡用，新程式碼請一律用 V2 API。