この記事の背景

Pythonのパッケージ管理ツール「Poetry」から高速なUVへの移行方法を解説。2025年の最新手法とツールを紹介し、プライベートリポジトリや依存関係のバージョン固定といった実践的な課題にも対応します。

PoetryからUVへの移行

問題定義

Poetryで管理されている既存プロジェクトをUVパッケージマネージャーに移行したいが、公式の移行ガイドが存在せず以下の課題に直面します:

• pyproject.tomlファイルの正しい変換方法
• Poetry固有セクション([tool.poetry])の適切な置き換え
• 依存関係のバージョン互換性維持
• プライベートリポジトリ認証の継承
• 開発用依存関係(devグループ)の移行

特に問題となる既存のpyproject.toml例:

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

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

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

推奨移行方法

migrate-to-uvツールを使う（2025年最新）

UV公式チーム推奨の最も簡潔な方法です。

# 移行ツールのインストール
uvx install migrate-to-uv

# プロジェクトディレクトリで実行
uvx migrate-to-uv

変換内容:

1. [tool.poetry]セクション → UV互換形式に自動変換
2. 依存関係のバージョン情報を維持
3. 開発用依存関係(devグループ)を保持
4. poetry.lock → uv.lockに変換
5. 不要なPoetryセクションを削除

移行後の確認ポイント

生成されたpyproject.tomlに以下のビルドシステム設定があることを確認:

[build-system]
requires = ["hatchling"]  # Poetry-coreから変更
build-backend = "hatchling.build"

移行後の操作

# 依存関係の同期（以前のpoetry install相当）
uv sync

# 新規パッケージ追加
uv add <package_name>

# パッケージ削除
uv remove <package_name>

プライベートリポジトリの対応方法

認証が必要な場合

Poetryでプライベートリポジトリを使用している場合、環境変数による認証設定が必要

設定例 (Gemfuryの場合):

export UV_EXTRA_INDEX_URL="https://$TOKEN:@pypi.fury.io/USERNAME/"

pyproject.tomlへの直接記載 (任意):

# プライベートリポジトリのURL指定
[[tool.uv.index]]
name = "private-repo"
url = "https://custom.pypi.org/simple/"

高度な移行ケース

依存関係のバージョン固定が必要な場合

Poetryのロックファイルと完全一致させたい時は事前にバージョン固定:

# Poetryのロックファイルからバージョンを抽出しpyproject.tomlを更新
import toml

def pin_versions(original_toml, lockfile):
    # 実装詳細は下記補助コード参照
    ...

バージョン固定スクリプト全文

from pathlib import Path
import toml

lock_data = toml.load(Path("poetry.lock"))
pyproject = toml.load(Path("pyproject.toml"))

locked_versions = {pkg["name"]: pkg["version"] for pkg in lock_data["package"]}

def pin_dependencies(section):
    for name, spec in list(section.items()):
        if name in locked_versions:
            section[name] = locked_versions[name]

pin_dependencies(pyproject["tool"]["poetry"]["dependencies"])
pin_dependencies(pyproject["tool"]["poetry"]["group"]["dev"]["dependencies"])

with Path("pyproject-pinned.toml").open("w") as f:
    toml.dump(pyproject, f)

使用手順:

# 1. バージョン固定した一時ファイル作成
python pyproject-fixer.py

# 2. 一時ファイルで移行実行
uvx migrate-to-uv -i pyproject-pinned.toml

# 3. 元のpyproject.tomlで再移行（UVがロックファイル優先）
uvx migrate-to-uv

ユーザー情報の移行

Poetryのauthors形式をUV形式に変換:

# Before
authors = ["名前 <email@example.com>"]

# After
authors = [
    {name = "名前", email = "email@example.com"}
]

代替移行ツール比較

ツール名	コマンド	長所	注意点
uv-migrator	uv-migrator .	複雑な設定を保持	ビルドシステムの手動設定が必要
PDM経由	uvx pdm import pyproject.toml	Poetry以外にも対応	依存解決が変わる可能性あり

移行後の検証

1. ビルドシステムの確認:

   uv pip list

2. 依存関係テスト:

   uv sync
   pytest tests/

3. ロックファイル整合性チェック:

   uv lock --refresh
   git diff uv.lock

::: success ベストプラクティス

1. migrate-to-uvで基本移行
2. プライベートリポジトリは環境変数で認証
3. クリティカルな依存関係はバージョン固定スクリプトを併用
4. 開発依存関係はuv sync --group devでインストール :::