Poetryとuvの二刀流：『ハイブリッドCI』がPythonエコシステムの限界を突破する理由
幾多のプロジェクトでCI/CDパイプラインのボトルネックと向き合ってきたアーキテクトなら、誰もが一度はこう叫びたくなる瞬間があるはずだ。
——「なぜ、Pythonの依存関係解決とインストールに毎ビルド数分も待たされるのか」と。
かつて、私たちは `pip` の脆弱な依存関係解決に怯え、`poetry` の登場によって美しく堅牢なロックファイルと決定論的なビルドを手に入れた。だが、Poetryは成熟と引き換えに、依存関係の解決フェーズ（特に巨大な科学計算ライブラリやAI/ML系スタックが絡む場合）において、依然として重いオーバーヘッドを抱えている。
ここに、Rust製パッケージマネージャである `uv` が現れた。
`uv` は単なる「速いpip」ではない。並列ダウンロード、高度なキャッシュ機構、そして驚異的な速度の仮想環境構築能力を持つ、ゲームチェンジャーだ。しかし、エンタープライズの厳格なプロダクション環境や複雑なモノレポにおいて、Poetryの洗練されたワークスペース管理やパブリッシング機能、そして厳密なメタデータ管理を完全に手放すことはリスクを伴う。
ならば、答えは一つだ。
「依存関係の解決とパッケージのビルド・配信はPoetryに委ね、CI上のテスト実行や一過性の環境構築はuvの爆速キャッシュで圧倒的に高速化する」。
本稿では、この2つのツールを極限まで調停させ、CIパイプラインの実行時間を極限まで削ぎ落とす『ハイブリッドCI』のアーキテクチャを、実務レベルのコードと低レイヤの挙動解説とともに解き明かす。
—
1. 内部アーキテクチャの理解：なぜPoetryとuvの組み合わせが最強なのか
まず、両者の内部挙動とデータフローの差分を正確に把握する必要がある。
- Poetry (`poetry.lock`):
PEP 508に準拠し、依存関係のグラフを緻密に解決する。ロックファイルの信頼性はピカイチだが、依存解決アルゴリズムとPythonで実装されたインストーラ（あるいは仮想環境への書き込み）のI/Oボトルネックにより、CIでのコールドスタートが重くなりがちである。
- uv (`uv pip`, `uv venv`):
コアがRustで書かれており、システムのシステムコールを効率的に叩く。特に `.whl` のローカルキャッシュ戦略とグローバルキャッシュディレクトリ（`~/.cache/uv`）の共有機構が極めて洗練されており、数千のパッケージを持つ環境であっても、数秒で仮想環境を構築・同期できる。
ハイブリッド戦略の設計思想
この2つのツールを共存させる鍵は、「Poetryのロックファイルを単一の真実のソース（Single Source of Truth）として使い、実際の環境構築・同期のエンジンだけをuvに差し替える」という点にある。
Poetryで生成された `poetry.lock` から `requirements.txt`（または直接uvが読める形式）へ変換し、uvの強力なキャッシュレイヤに乗せることで、依存解決の安全性を担保しながら、実行速度はRustネイティブの領域へと引き上げるのだ。
—
2. 実践：GitHub ActionsにおけるハイブリッドCIパイプラインの構築
百聞は一見に如かず。エンタープライズ水準の堅牢性と速度を両立させたGitHub Actionsのワークフロー定義を提示する。ここでは、キャッシュのヒット率を最大化するためのディレクトリ構造と環境変数のチューニングに注目してほしい。
name: Hybrid CI (Poetry + uv)
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
# ジョブ全体で利用する環境変数を定義。uvのキャッシュパスを固定化し、CIのランナーが変わってもキャッシュが効くようにする
env:
UV_CACHE_DIR: ${{ github.workspace }}/.uv-cache
POETRY_VERSION: “1.8.3”
PYTHON_VERSION: “3.11”
steps:
# 1. リポジトリのチェックアウト（深度を浅くしてI/Oを削減）
- name: Checkout Repository
uses: actions/checkout@v4
# 2. Pythonのセットアップ
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: ${{ env.PYTHON_VERSION }}
# 3. 超高速なuvのインストール（公式のインストーラースクリプトを使用）
- name: Install uv
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo “$HOME/.cargo/bin” >> $GITHUB_PATH
# 4. Poetryのインストール（ビルド・ロックファイル検証用）
- name: Install Poetry
run: |
pip install poetry==$POETRY_VERSION
# 5. uvのキャッシュディレクトリの永続化設定
# poetry.lockのハッシュ値をキャッシュキーにして、依存関係が変わった時だけキャッシュを無効化する
- name: Restore uv Cache
uses: actions/cache@v4
with:
path: ${{ env.UV_CACHE_DIR }}
key: uv-cache-${{ runner.os }}-${{ hashFiles(‘poetry.lock’) }}
restore-keys: |
uv-cache-${{ runner.os }}-
# 6. Poetryのロックファイルからuvが高速に読めるrequirements.txtを生成
# ※Poetryで直接ロック解決を行い、その結果をuvに渡すことで整合性を完全に維持する
- name: Export requirements from Poetry
run: |
poetry export -f requirements.txt –output requirements.txt –without-hashes
# 7. uvを用いた爆速の仮想環境構築とパッケージインストール
# uv venvで仮想環境を作り、uv pip syncでrequirements.txtをミリ秒単位で同期する
- name: Set up virtual environment and install dependencies with uv
run: |
uv venv .venv –python ${{ env.PYTHON_VERSION }}
# 仮想環境をアクティベートせずにuvの –python / –virtualenv オプションで直接流し込むことも可能
.venv/bin/pip install –upgrade pip
uv pip sync requirements.txt –python .venv/bin/python
# 8. テストの実行（高速化された仮想環境を利用）
- name: Run Pytest
run: |
.venv/bin/pytest tests/ –cov=src –cov-report=xml
# 9. コード品質の検証（Poetry環境自体の整合性チェックも兼ねる）
- name: Verify Poetry Lock Consistency
run: |
poetry check –lock
このワークフローの圧倒的なアドバンテージ
- 依存関係の整合性: `poetry export` を挟むことで、Poetryが計算した厳密なバージョン制約（`poetry.lock`）を一切崩すことなく維持している。
- キャッシュの効率性: `uv` はダウンロードした `.whl` やビルド済みアーティファクトを `UV_CACHE_DIR` に保持する。GitHub Actionsのキャッシュ機構と組み合わせることで、2回目以降のビルドではネットワークをほぼ使用しない。
—
3. Dockerコンテナ環境における完全自動構成の極意
ローカル開発環境や、本番前のステージングビルドを行うDockerイメージにおいても、このハイブリッド思想を適用することで、レイヤーキャッシュの効率を劇的に高めることができる。
マルチステージビルドを用い、「Poetryによるロック解決」と「uvによる軽量インストール」を分離したDockerfileの実装例を示す。
==========================================
Stage 1: ビルダー＆依存関係エクスポートステージ
==========================================
FROM python:3.11-slim AS builder
WORKDIR /app
必要なシステムパッケージの導入
RUN apt-get update && apt-get install -y –no-install-recommends \
curl \
build-essential \
&& rm -rf /var/lib/apt/lists/
Poetryのインストール
RUN pip install –no-cache-dir poetry==1.8.3
プロジェクト設定ファイルをコピー
COPY pyproject.toml poetry.lock ./
poetry.lockからrequirements.txtをエクスポート
RUN poetry export -f requirements.txt –output requirements.txt –without-hashes
==========================================
Stage 2: ランタイムステージ (uvによる高速インストール)
==========================================
FROM python:3.11-slim AS runtime
WORKDIR /app
uvバイナリを公式イメージから直接マルチステージコピー（curlすら本番イメージに残さないセキュリティ配慮）
COPY –from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
システムのPython環境に直接、あるいは仮想環境にuvで一括インストール
–system フラグを使用することでコンテナ内のグローバルPython環境へ高速同期
COPY –from=builder /app/requirements.txt .
RUN uv pip install –system –no-cache-dir -r requirements.txt
アプリケーションコードのコピー
COPY . .
エントリポイントの設定
CMD [“python”, “-m”, “src.main”]
アーキテクトの視点：なぜこのDockerfileが優れているのか
1. ビルドツールの分離: 本番ランタイムイメージに重いPoetry本体やビルドチェーン（`build-essential` 等）を持ち込まないため、イメージサイズが極小化され、セキュリティ脆弱性（CVE）の露出面を最小限に抑えられる。
2. uvのバイナリ直コピー: `ghcr.io/astral-sh/uv` からコンパイル済みの単一バイナリを `COPY` するだけなので、ランタイムイメージのビルドが数秒で完了する。
—
4. 運用上の罠と回避策（トラブルシューティング）
ハイブリッドCIを導入する現場で、アーキテクトが直面しがちな「罠」と、そのレイヤードな解決策を共有しておこう。
トラブル1: `poetry export` がプライベートレジストリ（ArtifactoryやAWS CodeArtifact等）の認証情報を含められない
- 原因: `poetry export` はデフォルトでパブリックなPyPIのURLを生成するため、社内リポジトリやプライベートパッケージの認証情報（トークン等）がrequirements.txtから抜け落ちる。
- 解決策: Poetryの認証情報を環境変数経由で設定した上で、export前にpoetryのソース設定を反映させるか、uv側がネイティブに解釈する `pyproject.toml` を直接参照させるオーバーライド手法を用いる。
# uvはpoetry.lockを直接解釈する実験的機能も持つが、安定性を重視するなら環境変数でクレデンシャルを注入した上でuv pip syncを実行する
export UV_INDEX_URL=”https://__token__:${PRIVATE_PYPI_TOKEN}@pypi.internal.example.com/simple”
uv pip sync requirements.txt
トラブル2: キャッシュの肥大化によるCIランナーの圧迫
- 原因: `uv` は非常にアグレッシブにキャッシュを溜め込むため、長期間運用すると `.uv-cache` が数GB規模に膨れ上がり、GitHub Actionsのキャッシュ上限（通常1リポジトリあたり10GB）を圧迫する。
- 解決策: 定期的なキャッシュのパージ戦略を導入するか、古いキャッシュのエントリを自動削除するスクリプトをCIの夜間バッチ等で走らせる。また、uv自体のキャッシュ管理コマンドを利用する。
# uvのキャッシュクリーンアップコマンド
uv cache prune –ci
—
5. 結び：開発体験（DX）とパフォーマンスの極限融合へ
ツールを単体で盲信し、「すべてをPoetryでやるべきだ」「いや、すべてをuvに移行しろ」と極端な思想に走るのは、シニアエンジニアリングの放棄に等しい。
- Poetry は、人間が読むためのメタデータ、厳密な依存関係ツリー、そしてエコシステム標準としての美しさを守る「守り」の要塞である。
- uv は、CI/CDのタイムアウト恐怖症を吹き飛ばし、開発者の待ち時間をゼロに近づける「攻め」の超加速エンジンである。
この二つを適材適所で組み合わせた『ハイブリッドCI』こそが、現代のPythonバックエンド開発において、保守性とスピードを極限まで高める唯一無二の戦術となる。
明日のパイプラインから、このアーキテクチャを導入し、ビルド待ちのコーヒーブレイクを不要なものにしてほしい。