Python開発環境に新風！Pyenv・Poetryから「uv」へ移行してみた

Python開発において、仮想環境の管理や依存関係の解決は非常に重要です。これまで「Pyenv」や「Poetry」を使用してきた方も多いでしょう。私自身も長らくこれらのツールを愛用してきましたが、最近注目されている「uv」というツールを試してみることにしました。

uvはRust製の高速パッケージマネージャーで、pipやPoetry、pyenvなどの機能を統合しています。公式ベンチマークでは、「キャッシュなしで8〜10倍、キャッシュありで80〜115倍」の速度向上を実現するとされています。この圧倒的な性能と機能性を試した結果をこの記事で詳しく解説します。

---

uvとは？

まず、「uv」の基本情報と特徴を整理しましょう。

• Rust製の高速性
  pipやPoetryと比較し、依存関係解決やパッケージインストールが圧倒的に速い（キャッシュなしで8〜10倍、キャッシュありで80〜115倍）。
• 仮想環境作成の高速性
  python -m venvやvirtualenvと比べても大幅に高速化。
• 柔軟な依存関係解決
  --python-versionオプションで特定バージョン向けの依存関係解決が可能。さらに-o overrides.txtオプションで依存関係の競合問題を柔軟に解決。
• グローバルキャッシュ機能
  再ダウンロードや再ビルドを回避し、高速化を実現。HTTPキャッシュヘッダー、Gitコミットハッシュ、ローカルファイルの更新時刻ベースで効率的に動作。
• GitやURL依存関係対応
  GitリポジトリやURLから直接依存関係を追加可能。
• プラットフォーム互換性への配慮
  requirements.txtファイルはプラットフォーム固有になる可能性があり、異なる環境間で移植性が低い場合があります。
• マルチプラットフォーム対応
  Linux、Windows、macOSで動作。

uvのgithubページのリンクは以下です。

GitHub

GitHub - astral-sh/uv: An extremely fast Python package and project manager, written in Rust. An extremely fast Python package and project manager, written in Rust. - astral-sh/uv

---

uvのセットアップ手順

1. インストール

uvは以下の方法でインストール可能です。私はmacOSでHomebrewを利用しました。

brew install uv

その他のインストール方法：

• スクリプト経由（macOS/Linux）

  curl -LsSf https://astral.sh/uv/install.sh | sh

• PyPIまたはpipx経由

  pip install uv
  pipx install uv

2. シェル補完の設定

インストール後はシェル補完を有効化することでコマンド入力が効率化されます。

# zshの場合
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
source ~/.zshrc

3. 初期設定

Pythonバージョンを確認し、必要なバージョンをインストールします。

uv python list --all-versions
uv python install 3.11.6

4. 仮想環境作成と初期化

プロジェクトごとに仮想環境を作成します。

uv venv --python 3.11.6

作成された仮想環境は.venvディレクトリ内に格納されます。

---

uvの基本的な使い方

仮想環境管理

仮想環境作成後は以下のコマンドでアクティベートできます。

source .venv/bin/activate

パッケージ管理コマンド

以下は主要なパッケージ管理コマンドです。

# パッケージインストール
uv pip install numpy

# パッケージ削除
uv pip uninstall numpy

# requirements.txtからインストールする場合
uv pip install -r requirements.txt

# pyproject.toml更新後のロックファイル生成（依存関係固定）
uv pip compile pyproject.toml -o requirements.txt

# ロックファイルに基づく依存関係同期（環境再現）
uv pip sync

# オーバーライドファイルによる依存関係変更（例: overrides.txt）
uv pip compile pyproject.toml -o requirements.txt -o overrides.txt

# Gitリポジトリから直接インストールする場合
uv pip install git+https://github.com/example/repo.git@main

また、依存関係ツリーの表示には以下を使用します。

uv pip tree

---

高度な機能：キャッシュ管理と柔軟な依存関係解決

キャッシュ管理機能

キャッシュディレクトリの管理には以下のコマンドが利用できます。

# キャッシュ全削除（すべて消去）
uv cache clean

# 特定パッケージのみ削除（例: ruff）
uv cache clean ruff

# 未使用キャッシュのみ削除（効率化）
uv cache prune

# CI/CD向けキャッシュ最適化削除（未使用ビルドデータのみ削除）
uv cache prune --ci 

キャッシュ動作の詳細：

1. HTTPキャッシュヘッダー対応：レジストリから取得した依存関係情報を効率的に再利用。
2. Gitコミットハッシュベース：特定コミットへの変更がない限り再ダウンロード不要。
3. ローカルファイル更新時刻ベース：ローカル依存関係が変更されていない場合は再ビルド不要。

柔軟な依存関係解決機能

特定バージョン向けや競合回避用に以下のオプションが活用できます：

# 特定Pythonバージョン向けロックファイル生成（例: Python 3.11用）
uv pip compile pyproject.toml --python-version "3.11"

# 最低互換バージョンによるテスト用ロックファイル生成（例: lowest-requirements.txt）
uv pip compile pyproject.toml --resolution=lowest -o lowest-requirements.txt

# オーバーライドファイルによる柔軟な依存関係調整（例: overrides.txt）
uv pip compile pyproject.toml -o requirements.txt -o overrides.txt

---

実際に使ってみた感想

良かった点

1. 圧倒的な速度
   キャッシュなしでも8〜10倍速く、キャッシュありでは80〜115倍もの速度向上が体感できました。
2. 統合性
   Pythonバージョン管理からパッケージ管理まで一つのツールで完結するため、ツールチェーンがシンプルになり効率的です。
3. 柔軟な操作性
   --python-versionや-o overrides.txtなど、高度なプロジェクト要件にも対応可能でした。
4. キャッシュ機能
   HTTPヘッダーやGitコミットハッシュベースのキャッシングが非常に効果的でした。
5. Gitリポジトリ対応
   Gitリポジトリから直接依存関係を追加できる点も魅力的です。

改善してほしい点

1. プラットフォーム互換性への注意喚起不足
   requirements.txtファイルがプラットフォーム固有になる場合があるため、異なる環境間で注意が必要です。
2. 制限事項への対応
   .egg依存関係やGit editableインストールがサポートされていない点は注意が必要です。
3. ドキュメント不足
   現時点では公式ドキュメントが少なく、一部情報はGitHubリポジトリ頼みになっています。

---

結論：Pyenv・Poetryから移行する価値はある？

結論として、「高速性」と「統合性」を重視する方には間違いなくおすすめです。特に、大規模プロジェクトや頻繁な依存関係変更がある場合、その恩恵は大きいでしょう。一方、小規模プロジェクトでは現状のツールでも十分かもしれません。

ただし、一部制限事項（.egg依存関係非対応など）とプラットフォーム互換性には注意が必要です。今後も継続的な改善が期待できるツールなので、一度試してみる価値はあります。「Pyenv」や「Poetry」に慣れている方でも、新しい選択肢として検討してみてはいかがでしょうか？

---

次のステップ：あなたも試してみよう！

• uv公式サイトからインストール方法を確認する。
• 小規模プロジェクトで試験運用し、その利便性を体感する。
• 移行時には既存プロジェクトのバックアップ（特にpyproject.toml）を忘れずに！

Python開発環境構築の新しい時代へ、一歩踏み出しましょう！