しとちゃぶろぐ

Pythonの開発環境では、パッケージ管理ツールとして長らくpipやpoetryが使用されてきました。しかし、これらのツールには以下のような課題がありました：

• 依存関係の解決が遅い
• クロスプラットフォームでの一貫性が不十分
• 環境管理が複雑

これらの課題を解決するために開発されたのがuvです。Rustで実装されたuvは、高速で安全、そして使いやすいパッケージマネージャーとして注目を集めています。

• Rustによる実装で、依存関係の解決が従来のツールと比べて数倍高速
• 効率的なキャッシュ機構により、再インストールも高速

• プラットフォーム間で一貫したロックファイル
• Windows、macOS、Linuxで同じ動作を保証

• 直感的なコマンド体系
• 最小限の設定で開始可能

💡 注意: インストール前の確認事項

• Python 3.8以上が必要です
• システム管理者権限が必要な場合があります

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

インストール後の確認：

uv --version

PowerShellで実行：

irm https://astral.sh/uv/install.ps1 | iex

インストール後の確認：

uv --version

# pipを使用
pip install uv

# Homebrewを使用（macOS）
brew install uv

🔍 トラブルシューティング:

• インストール後にuvコマンドが見つからない場合は、PATHの設定を確認してください
• Windowsの場合、PowerShellの実行ポリシーの変更が必要な場合があります

📁 推奨プロジェクト構造:

Copy

my-project/
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
├── tests/
│   └── __init__.py
├── .gitignore
├── pyproject.toml
└── README.md

# 新しいプロジェクトを作成
uv init my-project

# プロジェクトディレクトリに移動cd my-project

# 開発用の仮想環境を作成
uv venv

📝 pyproject.tomlの例:

Copy

[project]
name = "my-project"
version = "0.1.0"
description = "My Python Project"
requires-python = ">=3.8"
dependencies = []

[project.optional-dependencies]
dev = ["pytest", "black", "ruff"]

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

🚀 補足:

• src/レイアウトを使用することで、テスト時にインストール問題を早期に発見できます
• .gitignoreには.venv/や__pycache__/を追加することを推奨します
• 必要に応じてdocs/ディレクトリを追加してドキュメントを管理できます

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

# 開発用パッケージのインストール
uv pip install --dev pytest

# requirements.txtからのインストール
uv pip install -r requirements.txt

🔧 一般的なユースケース別依存関係例:

Copy

# Web開発用の依存関係
uv add fastapi uvicorn python-jose[cryptography]
uv add --dev httpx pytest-asyncio

# データサイエンス用の依存関係
uv add pandas numpy scikit-learn matplotlib
uv add --dev jupyter nbconvert

# CLI開発用の依存関係
uv add typer rich click
uv add --dev pytest-cov black

# 基本的な依存関係の管理
uv add requests# 単一パッケージの追加
uv add 'requests>=2.30.0'# バージョン指定での追加
uv add requests[security]# エクストラ機能の追加# 開発用依存関係の追加
uv add --dev pytest# テスト用パッケージ
uv add --dev black ruff# コード品質管理ツール# 依存関係の削除
uv remove requests# パッケージの削除# 依存関係の更新
uv add --upgrade requests# 特定パッケージの更新
uv pip freeze > requirements.txt# 依存関係のエクスポート

💡 ベストプラクティス:

• 本番環境の依存関係と開発用依存関係は明確に分けましょう
• バージョン制約は必要な場合のみ指定しましょう
• 定期的に依存関係を更新して、セキュリティ修正を取り入れましょう

# 依存関係のロック
uv pip compile requirements.in -o requirements.txt# requirements.inからロックファイルを生成
uv pip compile pyproject.toml -o requirements.txt# pyproject.tomlからロックファイルを生成
uv pip compile setup.py -o requirements.txt# setup.pyからロックファイルを生成
uv pip freeze | uv pip compile - -o requirements.txt# 現在の環境をロック# プロジェクトの依存関係を同期
uv sync# 全ての依存関係を同期
uv pip sync requirements.txt# 特定のrequirements.txtと同期# ロックファイルの更新
uv lock# ロックファイルを更新

💡 パッケージロックのポイント:

• 複数のソースファイル（requirements.in, pyproject.toml, setup.py）からロックファイルを生成可能
• 現在の環境から直接ロックファイルを生成することも可能
• ロックファイルを使用することで、環境間の一貫性を保証

# 特定のバージョンのPythonをインストール
uv python install 3.12

# インストール済みのバージョンを確認
uv python list

# 一時的な環境でツールを実行
uvx ruff check .

# ツールの永続的なインストール
uv tool install ruff

# キャッシュのクリア
uv cache clean

# 未使用のキャッシュを削除
uv cache prune

# 最低バージョンでの依存関係解決
uv pip install --resolution=lowest requests

# 特定のPythonバージョンに対する解決
uv pip install --python-version=3.7 requests

# 依存関係のオーバーライド
uv pip install -o overrides.txt requests

🔍 解決戦略の特徴:

• デフォルトでは最新の互換バージョンを優先
• -resolution=lowestで最低互換バージョンをテスト可能
• -python-versionで対象Pythonバージョンを指定可能
• overrides.txtで依存関係の宣言を上書き可能

1. 現在の依存関係をエクスポート：
   Copy

   pip freeze > requirements.txt
   

2. uvでプロジェクトを初期化：
   Copy

   uv init my-project
   

3. 依存関係をインストール：
   Copy

   uv pip install -r requirements.txt
   

1. poetryのpyproject.tomlをuvの形式に変換
2. poetry.lockファイルをuv.lockに置き換え：
   Copy

   uv lock
   

3. 環境を同期：
   Copy

   uv sync
   

# ベースイメージの選択FROM python:3.12-slim

# uvのインストールCOPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
COPY --from=ghcr.io/astral-sh/uv:latest /uvx /bin/uvx

# プロジェクトのセットアップWORKDIR /app
COPY . .

# 依存関係のインストールRUN uv pip install -r requirements.txt

name: Python CI

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3

      - name: Install dependencies
        run: uv pip install -r requirements.txt

      - name: Run tests
        run: uv run pytest

問題：uvコマンドが見つからない

# 解決方法# PATHの確認と追加echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

問題：パッケージの競合によるuv syncの失敗

# 解決方法# ロックファイルの再生成
uv lock --upgrade
uv sync

問題：古いキャッシュによる動作不良

# 解決方法# キャッシュのクリア
uv cache clean

仮想環境の作成やパッケージの更新時（キャッシュ済み）：

• 依存関係の解決: uvは従来のツールより80-115倍高速
• 環境作成: python -m venvより約80倍、virtualenvより約7倍高速

新規環境での実行（キャッシュなし）：

• パッケージインストール: pipと比較して8-10倍高速
• 依存関係の解決: 大規模プロジェクトでも数秒で完了

💡 高速化の秘密:

• グローバルモジュールキャッシュの活用
• Copy-on-Writeとハードリンクによるディスクスペースの最適化
• Rustによる効率的な実装

• プラットフォーム固有のrequirements.txtの生成
  • poetryやpdmのようなプラットフォーム非依存のロックファイルは未対応
• 一部のlegacy機能（.eggディストリビューションなど）は未サポート

• 依存関係の解決が遅く、大規模プロジェクトで数時間かかることも
• 依存関係の設定ファイルが適切に管理されていないと「依存性の臭い」が発生
• 実行環境の復元時に推論の成功率が低くなる可能性

uvは、Pythonのパッケージ管理に革新をもたらす新世代のツールです。高速な処理、クロスプラットフォーム対応、シンプルな使用方法という特長を持ち、多くの開発者に支持されています。

特に以下のような場合にuvの使用をお勧めします：

• 大規模なプロジェクトで依存関係の解決に時間がかかっている
• 複数のプラットフォームでの開発が必要
• シンプルで効率的なパッケージ管理を求めている

uvは日々進化を続けており、Pythonの開発環境をより快適にする強力なツールとなっています。