如何从Poetry迁移至UV包管理器？需调整哪些pyproject.toml配置？

一、基础迁移步骤 #

• 安装UV：执行 curl -LsSf https://astral.sh/uv/install.sh | sh（根据操作系统选择对应安装方式）
• 清理残留文件（可选）：删除Poetry生成的poetry.lock和.venv虚拟环境目录，避免新旧工具冲突
• 生成UV锁文件：运行 uv lock，UV会自动读取现有pyproject.toml中的Poetry依赖配置，生成uv.lock
• 同步依赖并创建虚拟环境：执行 uv sync，完成依赖安装并生成UV的虚拟环境

二、pyproject.toml配置修改 #

你的现有配置大部分可直接复用，仅需调整以下关键部分：

1. 替换Poetry专属元数据（可选但推荐） #

UV兼容PEP 631标准的项目配置，建议将[tool.poetry]区块替换为标准[project]元数据，更贴合UV的原生支持：

[project]
name = "name"
version = "1.6.0"
description = ""
authors = [
    "...",
]
maintainers = [
    "...",
]
readme = "README.md"
requires-python = "^3.12"

同时把原[tool.poetry.dependencies]中的业务依赖移到[project.dependencies]：

[project.dependencies]
fastapi = "^0.115.2"
uvicorn = { version = "^0.32.0", extras = ["standard"] }
pydantic = "^2.5.3"
pydantic-settings = "^2"

开发依赖则移到标准的[project.group.dev.dependencies]分组：

[project.group.dev.dependencies]
pytest = "^8.3.3"
flake8 = "~7.1.1"
mypy = "^1.12"

2. 保留第三方工具配置 #

[tool.isort]、[tool.mypy]、[tool.pytest.ini_options]、[tool.coverage.run]、[tool.coverage.report]这些区块无需任何修改，UV不会干涉第三方工具的配置逻辑，它们可以正常工作。

三、build-system部分的处理 #

不需要强制替换为UV专属内容，UV支持多种构建后端：

• 继续使用poetry-core：保持原配置不变即可，UV会正常调用它完成项目构建
• 切换到UV推荐的后端（可选）：如果想更换构建工具，可以改成hatchling或setuptools，例如：

[build-system]
requires = ["hatchling>=1.21.0"]
build-backend = "hatchling.build"

或者：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

四、额外注意事项 #

• UV命令与Poetry对应关系：uv add <包名>对应poetry add，uv remove <包名>对应poetry remove，uv run <命令>对应poetry run
• 自定义虚拟环境路径：可添加[tool.uv]区块指定路径：

[tool.uv]
virtual-environment = ".venv"

内容的提问来源于stack exchange，提问作者mdegis