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

安裝與環境

安裝 Pydantic 只要一行指令：uv add pydantic 或 pip install pydantic。目前的 Pydantic V2（2.14 版）需要 Python 3.10 以上，核心驗證引擎 pydantic-core 會以預先編譯好的套件一起安裝，不需要自己裝 Rust。本頁說明安裝方式、如何確認版本，以及常用的選用套件。

如何安裝 Pydantic？

推薦用 uv 管理專案與依賴，速度快且會自動建立虛擬環境：

uv init my-project
cd my-project
uv add pydantic

習慣使用 pip 時，先建立虛擬環境再安裝：

python -m venv .venv
source .venv/bin/activate  # Windows：.venv\Scripts\activate
pip install pydantic

如何確認安裝的版本？

import pydantic

print(pydantic.VERSION)  # 例如 2.14.0

也可以印出完整的環境資訊，回報問題時很有用：

python -c "import pydantic.version; print(pydantic.version.version_info())"

確認是 V2

版本號開頭是 1. 代表是舊版 V1，本站的 model_dump、field_validator 等 API 在 V1 不存在。請升級：uv add "pydantic>=2" 或 pip install -U pydantic。

有哪些常用的選用套件？

Pydantic 把部分功能拆成額外套件，需要時再安裝：

套件／extra	用途	安裝指令
`pydantic[email]`	啟用 `EmailStr`、`NameEmail` 型別	`uv add "pydantic[email]"`
`pydantic[timezone]`	跨平台時區資料	`uv add "pydantic[timezone]"`
`pydantic-settings`	從環境變數／`.env` 讀取設定	`uv add pydantic-settings`
`pydantic-extra-types`	電話號碼、國家代碼、顏色等額外型別	`uv add pydantic-extra-types`

pydantic-settings 的用法見 Settings 設定管理。

編輯器要怎麼設定？

Pydantic 模型就是普通的 Python 類別，VS Code（Pylance）、PyCharm 都能直接提供自動完成與型別檢查。使用 mypy 時，建議在設定中啟用 Pydantic 外掛，讓 mypy 正確理解模型的建構子：

# pyproject.toml
[tool.mypy]
plugins = ["pydantic.mypy"]