将 poetry 项目迁移到 python uv 的核心做法是：使用 uv export 命令导出锁定依赖，生成标准 requirements.txt 文件，随后在 pyproject.toml 中移除 poetry 配置并添加 [project] 元数据，最后通过 uv pip install -r requirements.txt 完成环境重建。此过程能保留原有的精确依赖版本，同时利用 uv 的底层能力实现更快的安装和更简洁的项目结构。
如何从 Poetry 导出兼容的依赖列表
Poetry 原生管理的 poetry.lock 文件无法被 pip 或 uv pip 直接读取，必须转换为标准的 requirements.txt 格式。在已安装 Poetry 的环境中运行 uv export 是最稳妥的方式，它能解析锁文件中的复杂约束（如 extras、git 依赖）并输出符合 PEP 508 规范的文本。执行该命令后，终端会打印出所有依赖及其哈希值，重定向到文件即可用于后续安装。
uv export > requirements.txt # 或者在旧版 uv 中使用 uv pip compile pyproject.toml -o requirements.txt
生成的 requirements.txt 包含类似 requests==2.31.0 --hash=sha256:... 的行。这些哈希值对于确保生产环境的一致性至关重要，uv pip install 默认会验证这些哈希，防止依赖包被篡改。如果项目中存在 Git 依赖或本地路径依赖，uv export 通常能将其转换为可安装的 URL 或相对路径格式，但需手动检查转换后的路径在当前机器上是否有效。
立即学习“Python免费学习笔记（深入）”；
如何重构 pyproject.toml 以适配 uv
迁移的第二步是清理 pyproject.toml。Poetry 使用 [tool.poetry] 区块定义项目元数据和依赖，而 uv 遵循 PEP 621 标准，使用 [project] 区块。需要删除整个 [tool.poetry] 部分，并在其位置添加 [project]，其中包含 name、version、description 和 dependencies。注意，dependencies 的值是一个字符串列表，而非 Poetry 中的字典对象。
# 迁移前 (Poetry)
[tool.poetry]
name = "my-project"
version = "0.1.0"
dependencies = {
requests = "^2.28.0",
flask = {extras = ["async"], version = "^2.0"}
}
# 迁移后 (uv / PEP 621)
[project]
name = "my-project"
version = "0.1.0"
description = "A migrated project"
dependencies = [
"requests>=2.28.0",
"flask[async]>=2.0.0"
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
上述代码展示了关键的语法差异。Poetry 的 ^2.28.0 范围运算符在 PEP 621 中不被直接支持，通常需要转换为 >=2.28.0 或使用 uv 的特定功能处理。为了简化迁移，建议先使用 uv 初始化一个新项目，复制其 [build-system] 配置（通常推荐 hatchling 或 setuptools），然后将原项目的名称和描述填入 [project]。依赖列表需要手动调整格式，将 Poetry 的键值对转为字符串。
如何处理 Poetry 特有的插件和脚本配置
Poetry 允许通过 [tool.poetry.scripts] 定义命令行入口点，并通过 [tool.poetry.plugins] 注册插件。这些配置在迁移到 uv 后不会自动生效，因为 uv 本身不执行这些脚本注册逻辑，而是依赖构建后端（如 hatchling 或 setuptools）。需要在 [project] 中添加 scripts 字段来替代 scripts 块，例如：scripts.my-command = "my_package.module:function"。对于插件，需查阅所用构建后端的文档，通常在 [project.entry-points] 中定义。
[project] name = "my-project" version = "0.1.0" dependencies = [] [project.scripts] my-cli = "my_package.cli:main" [project.entry-points."my_plugin_group"] my_plugin = "my_package.plugin:MyPluginClass"
完成上述步骤后，删除 poetry.lock 和 .venv 目录，运行 uv sync 或 uv pip install -e . 即可重新建立虚拟环境和安装依赖。此时，项目完全由 uv 管理，不再依赖 Poetry CLI。若需恢复 Poetry 风格的依赖解析行为，可考虑使用 uv 的 add 命令，它会自动更新 pyproject.toml 并生成新的锁文件（虽然 uv 的锁文件格式与 Poetry 不同，但同样有效）。
