从Poetry迁移到UV包管理器

问题

当从Poetry迁移到UV时，开发者面临的主要挑战是：

1. 如何将现有pyproject.toml中的Poetry配置转换为UV兼容格式
2. 如何处理依赖组（如dev依赖）
3. 如何正确处理私有包仓库身份验证
4. 是否需要修改[build-system]部分
5. 如何确保依赖版本的一致性

迁移前典型的pyproject.toml结构包含：

# Poetry特有配置
[tool.poetry]
name = "name"
version = "1.6.0"

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.115.2"

[tool.poetry.group.dev.dependencies]
pytest = "^8.3.3"

# 构建系统设定
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

推荐迁移工具

1. 使用官方迁移工具 migrate-to-uv

推荐方法

这是UV官方推荐的迁移方案，支持Poetry项目的一键转换

步骤：

# 安装迁移工具
uvx install migrate-to-uv

# 进入项目目录
cd your-project

# 执行迁移命令
uvx migrate-to-uv

迁移工具会：

1. 移除所有[tool.poetry]相关配置
2. 保留依赖版本约束
3. 转换依赖组为UV格式
4. 生成uv.lock文件替代poetry.lock
5. 移除原始Poetry锁定文件

2. 处理私有仓库认证

如果使用私有PyPI仓库，需设置环境变量：

# 针对源配置中定义的私有源
export UV_INDEX_COMPANY_REPO_USERNAME=<username>
export UV_INDEX_COMPANY_REPO_PASSWORD=<password>

# 或者通过URL直接设置
export UV_EXTRA_INDEX_URL="https://$TOKEN:$TOKEN@pypi.example.com/"

手动迁移步骤

当无法使用自动工具时，可进行手动迁移：

1. 移除Poetry配置

删除所有以[tool.poetry]开头的配置节

2. 转换依赖组

将依赖组转换为UV格式：

- [tool.poetry.group.dev.dependencies]
+ [dependency-groups]
+ dev = ["pytest"]

3. 配置构建系统

重要

UV不依赖特定构建后端，但需要移除Poetry专用配置

[build-system]
requires = ["hatchling"]  # 可选用其他构建工具
build-backend = "hatchling.build"

4. 修正元数据字段

手动转换作者信息格式：

- authors = ["John Doe <john.doe@company.com>"]
+ authors = [{name = "John Doe", email = "john.doe@company.com"}]

迁移后文件示例

[project]
name = "name"
version = "1.6.0"
authors = [{name = "...", email = "..."}]

[project.dependencies]
python = "^3.12"
fastapi = "^0.115.2"
uvicorn = { version = "^0.32.0", extras = ["standard"] }

[dependency-groups]
dev = ["pytest~=8.3.3", "flake8~=7.1.1", "mypy^1.12"]

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

# 保留原有工具配置（如pytest, mypy等）
[tool.isort]
profile = "black"

依赖版本一致性处理

当迁移导致依赖版本变化时，可使用此脚本临时锁定版本：

from pathlib import Path
import toml

lock_path = Path("poetry.lock")
pyproject_path = Path("pyproject.toml")

with lock_path.open("r") as f:
    lock_data = toml.load(f)
    
with pyproject_path.open("r") as f:
    pyproject_data = toml.load(f)

# 从poetry.lock提取精确版本
locked_versions = {pkg["name"]: pkg["version"] for pkg in lock_data["package"]}

# 更新主依赖
for dep in pyproject_data["tool"]["poetry"]["dependencies"]:
    if dep in locked_versions:
        pyproject_data["tool"]["poetry"]["dependencies"][dep] = locked_versions[dep]

# 更新开发依赖
dev_deps = pyproject_data["tool"]["poetry"]["group"]["dev"]["dependencies"]
for dep in dev_deps:
    if dep in locked_versions:
        dev_deps[dep] = locked_versions[dep]

with pyproject_path.open("w") as f:
    toml.dump(pyproject_data, f)

使用流程：

1. 运行脚本固定版本 → 2. 执行迁移 → 3. 生成uv.lock → 4. 还原原始约束条件

迁移后操作

# 生成锁定文件
uv lock

# 安装所有依赖
uv sync

# 添加新包
uv add package-name

# 安装开发组依赖
uv sync --group dev

私有仓库配置

在pyproject.toml中添加：

[[tool.uv.index]]
name = "private-repo"
url = "https://pypi.company.com/simple/"

或通过环境变量设置：

export UV_GLOBAL_INDEX_URL="https://user:pass@pypi.company.com/simple/"

常见问题解决

1. 迁移后作者信息丢失

手动将格式从字符串转换为字典结构：

authors = [{name = "姓名", email = "邮箱"}]

2. 开发依赖未正确转换

确保使用正确的分组语法：

[dependency-groups]
dev = ["pytest", "flake8"]

3. 构建错误

检查是否已移除poetry-core依赖，更换为通用构建后端：

requires = ["hatchling"]  # 可选：setuptools, flit-core等

总结建议

1. 首选自动迁移工具：使用uvx migrate-to-uv处理大部分转换工作
2. 验证私有仓库配置：迁移前设置身份验证相关环境变量
3. 解决版本差异：使用临时锁定脚本保持版本一致
4. 手动检查关键字段：特别是作者信息和依赖分组配置
5. 测试构建流程：迁移后运行uv lock && uv sync验证安装

最佳实践

迁移完成后：

• 提交uv.lock到版本控制
• 完全移除Poetry相关文件（poetry.lock, poetry.toml）
• 在CI/CD中替换所有poetry install为uv sync