【Agent向け】uvの最新のdocumentまとめ

# uv: 高速なPythonパッケージ・プロジェクト管理ツール

uvは、Rustで書かれた非常に高速なPythonパッケージおよびプロジェクト管理ツールです。
LMLをベースとしたコーディングエージェントでの利用を想定した、この**自動生成**ドキュメントでは、uvの主要な機能と使い方について説明します。


## 目次

- [概要](#概要)
- [インストール](#インストール)
- [基本的な使い方](#基本的な使い方)
  - [プロジェクト管理](#プロジェクト管理)
  - [スクリプト実行](#スクリプト実行)
  - [ツール管理](#ツール管理)
  - [Pythonバージョン管理](#pythonバージョン管理)
  - [pipインターフェース](#pipインターフェース)
- [高度な機能](#高度な機能)
  - [キャッシュ](#キャッシュ)
  - [依存関係解決](#依存関係解決)
  - [ロックファイル](#ロックファイル)
  - [ワークスペース機能](#ワークスペース機能)
  - [設定ファイルとカスタマイズ](#設定ファイルとカスタマイズ)
- [トラブルシューティング](#トラブルシューティング)
- [パフォーマンス最適化](#パフォーマンス最適化)
- [実際のユースケース](#実際のユースケース)
- [TDDでの使用方法](#tddでの使用方法)
- [環境管理のベストプラクティス](#環境管理のベストプラクティス)

## 概要

uvは以下のような特徴を持つPythonパッケージおよびプロジェクト管理ツールです：

- 🚀 `pip`、`pip-tools`、`pipx`、`poetry`、`pyenv`、`twine`、`virtualenv`などを置き換える単一のツール
- ⚡️ `pip`よりも10〜100倍高速
- 🗂️ ユニバーサルロックファイルを含む包括的なプロジェクト管理機能
- ❇️ インライン依存関係メタデータをサポートしたスクリプト実行機能
- 🐍 Pythonバージョンのインストールと管理
- 🛠️ Pythonパッケージとして公開されているツールの実行とインストール
- 🔩 使い慣れたCLIで高速なパフォーマンスを提供するpip互換インターフェース
- 🏢 スケーラブルなプロジェクト向けのCargoスタイルのワークスペースをサポート
- 💾 依存関係の重複排除のためのグローバルキャッシュによる効率的なディスク使用
- ⏬ RustやPythonなしで`curl`や`pip`を使ってインストール可能
- 🖥️ macOS、Linux、Windowsをサポート

## インストール

### スタンドアロンインストーラーを使用する方法

macOSとLinuxの場合：

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

Windowsの場合：

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### PyPIからインストールする方法

pipを使用：

```bash
pip install uv
```

pipxを使用：

```bash
pipx install uv
```

スタンドアロンインストーラーでインストールした場合、最新バージョンに更新するには：

```bash
uv self update
```

## 基本的な使い方

### プロジェクト管理

uvは、ロックファイル、ワークスペースなどをサポートするプロジェクト依存関係と環境を管理します。

#### 新しいプロジェクトの作成

```bash
# 新しいプロジェクトを作成
uv init example
cd example

# 依存関係を追加
uv add ruff
```

#### 依存関係の管理

```bash
# 依存関係を追加
uv add requests

# バージョン制約を指定
uv add 'requests==2.31.0'

# Gitリポジトリから依存関係を追加
uv add git+https://github.com/psf/requests

# 依存関係を削除
uv remove requests

# 依存関係をアップグレード
uv lock --upgrade-package requests
```

#### コマンドの実行

```bash
# プロジェクト環境でコマンドを実行
uv run -- flask run -p 3000

# スクリプトを実行
uv run example.py

# 環境を手動で更新して有効化
uv sync
source .venv/bin/activate  # macOSとLinux
# または
source .venv\Scripts\activate  # Windows
```

#### ディストリビューションのビルド

```bash
# プロジェクトをビルド
uv build
```

### スクリプト実行

uvは、単一ファイルのスクリプトの依存関係と環境を管理します。

#### 依存関係のないスクリプトの実行

```bash
# 依存関係のないスクリプトを実行
uv run example.py

# 引数を渡す
uv run example.py hello world!

# 標準入力からスクリプトを読み込む
echo 'print("hello world!")' | uv run -
```

#### 依存関係のあるスクリプトの実行

```bash
# 依存関係を指定してスクリプトを実行
uv run --with rich example.py

# バージョン制約を追加
uv run --with 'rich>12,<13' example.py

# 複数の依存関係を指定
uv run --with rich --with requests example.py
```

#### スクリプトの依存関係の宣言

```bash
# スクリプトに依存関係を追加
uv add --script example.py 'requests<3' 'rich'
```

これにより、スクリプトの先頭に依存関係を宣言するTOMLセクションが追加されます：

```python
# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

# スクリプトの内容
```

#### 依存関係のロック

```bash
# スクリプトの依存関係をロック
uv lock --script example.py
```

これにより、スクリプトと同じディレクトリに`.lock`ファイル（例：`example.py.lock`）が作成されます。

#### 異なるPythonバージョンの使用

```bash
# デフォルトのPythonバージョンを使用
uv run example.py

# 特定のPythonバージョンを使用
uv run --python 3.10 example.py
```

### ツール管理

uvは、Pythonパッケージとして公開されているコマンドラインツールを実行およびインストールします。

#### ツールの実行

```bash
# ツールを一時的な環境で実行（uvxはuv tool runのエイリアス）
uvx ruff

# 引数を渡す
uvx pycowsay hello from uv

# 特定のパッケージからコマンドを実行
uvx --from httpie http

# 特定のバージョンを指定
uvx ruff@0.3.0 check

# 最新バージョンを指定
uvx ruff@latest check

# バージョン範囲を指定
uvx --from 'ruff>0.2.0,<0.3.0' ruff check

# エクストラを指定
uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

# 追加の依存関係を含める
uvx --with mkdocs-material mkdocs --help
```

#### ツールのインストール

```bash
# ツールをインストール
uv tool install ruff

# バージョンを指定してインストール
uv tool install 'httpie>0.1.0'

# Gitリポジトリからインストール
uv tool install git+https://github.com/httpie/cli

# 追加の依存関係を含めてインストール
uv tool install mkdocs --with mkdocs-material
```

#### ツールのアップグレード

```bash
# 特定のツールをアップグレード
uv tool upgrade ruff

# すべてのツールをアップグレード
uv tool upgrade --all
```

### Pythonバージョン管理

uvは、Pythonをインストールし、バージョン間の素早い切り替えを可能にします。

#### Pythonのインストール

```bash
# 最新のPythonバージョンをインストール
uv python install

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

# 複数のPythonバージョンをインストール
uv python install 3.11 3.12

# 代替Pythonの実装をインストール（例：PyPy）
uv python install pypy@3.10

# インストール済みのPythonバージョンを再インストール
uv python install --reinstall
```

#### Pythonバージョンの表示

```bash
# 利用可能およびインストール済みのPythonバージョンを表示
uv python list
```

### pipインターフェース

uvは、一般的な`pip`、`pip-tools`、`virtualenv`コマンドの代替として使用できます。

#### 要件ファイルのコンパイル

```bash
# プラットフォームに依存しない要件ファイルをコンパイル
uv pip compile docs/requirements.in \
   --universal \
   --output-file docs/requirements.txt
```

#### 仮想環境の作成

```bash
# 仮想環境を作成
uv venv
```

#### ロックされた要件のインストール

```bash
# ロックされた要件をインストール
uv pip sync docs/requirements.txt
```

## 高度な機能

### キャッシュ

uvは、以前の実行でアクセスした依存関係を再ダウンロード（および再ビルド）しないように、積極的なキャッシングを使用します。

#### キャッシュの制御

```bash
# すべての依存関係のキャッシュデータを再検証
uv sync --refresh
# または
uv pip install --refresh ...

# 特定の依存関係のキャッシュデータを再検証
uv sync --refresh-package flask
# または
uv pip install --refresh-package flask ...

# 既存のインストール済みバージョンを無視
uv sync --reinstall
# または
uv pip install --reinstall ...
```

#### キャッシュのクリア

```bash
# すべてのキャッシュエントリを削除
uv cache clean

# 特定のパッケージのキャッシュエントリを削除
uv cache clean ruff

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

# CI環境用にキャッシュを最適化
uv cache prune --ci
```

### 依存関係解決

uvは、要件のリストを取り、要件を満たすパッケージバージョンのリストに変換するプロセスである解決をサポートします。

#### 解決戦略

```bash
# 最新バージョンを使用（デフォルト）
uv pip compile requirements.in

# 可能な限り最低バージョンを使用
uv pip compile --resolution lowest requirements.in

# 直接依存関係に最低バージョンを使用
uv pip compile --resolution lowest-direct requirements.in
```

#### プレリリースの処理

```bash
# すべての依存関係でプレリリースを許可
uv pip compile --prerelease allow requirements.in
```

#### 依存関係の制約

```bash
# 制約ファイルを使用
uv pip compile --constraint constraints.txt requirements.in
```

#### 依存関係のオーバーライド

```bash
# オーバーライドファイルを使用
uv pip compile --override overrides.txt requirements.in
```

pyproject.tomlでは、`tool.uv.override-dependencies`を使用してオーバーライドのリストを定義できます。

#### 再現可能な解決

```bash
# 特定の日付より前に公開されたディストリビューションに制限
uv pip compile --exclude-newer 2023-10-16T00:00:00Z requirements.in
```

### ロックファイル

uvのロックファイル（`uv.lock`）は、プラットフォームに依存しないユニバーサルな解決を使用して作成され、プラットフォーム間で移植可能です。

#### ロックファイルの作成と更新

```bash
# ロックファイルを作成または更新
uv lock

# 特定のパッケージをアップグレード
uv lock --upgrade-package requests
```

#### ロックファイルの同期

```bash
# ロックファイルに基づいて環境を更新
uv sync
```

### ワークスペース機能

uvは、Cargoスタイルのワークスペースをサポートしており、複数のPythonパッケージを単一のリポジトリ（モノレポ）で管理できます。これにより、大規模なプロジェクトや複数のパッケージを含むプロジェクトの管理が容易になります。

#### ワークスペースの作成

ワークスペースを作成するには、ルートディレクトリに`pyproject.toml`ファイルを作成し、`[tool.uv.workspace]`セクションを追加します：

```toml
[tool.uv.workspace]
members = ["packages/*"]
```

この例では、`packages`ディレクトリ内のすべてのディレクトリがワークスペースのメンバーとして扱われます。

#### ワークスペースの構造

典型的なワークスペースの構造は以下のようになります：

```
my-workspace/
├── pyproject.toml        # ワークスペースの設定
├── uv.lock               # 共有ロックファイル
├── packages/
│   ├── package-a/
│   │   ├── pyproject.toml  # パッケージAの設定
│   │   └── src/
│   │       └── package_a/
│   │           └── ...
│   └── package-b/
│       ├── pyproject.toml  # パッケージBの設定
│       └── src/
│           └── package_b/
│               └── ...
└── .venv/                # 共有仮想環境
```

#### ワークスペースの依存関係管理

ワークスペース内のパッケージは、他のワークスペースメンバーに依存することができます：

```toml
# packages/package-b/pyproject.toml
[project]
name = "package-b"
version = "0.1.0"
dependencies = ["package-a"]
```

ワークスペース全体の依存関係を管理するには：

```bash
# ワークスペースルートで実行
uv lock
uv sync
```

#### ワークスペースコマンドの実行

特定のパッケージに対してコマンドを実行するには：

```bash
# パッケージディレクトリで実行
cd packages/package-a
uv run -- pytest

# または、ワークスペースルートから特定のパッケージを指定
uv run --package package-a -- pytest
```

### 設定ファイルとカスタマイズ

uvは、`pyproject.toml`ファイルの`[tool.uv]`セクションを通じて様々な設定をカスタマイズできます。

#### 基本的な設定

```toml
[tool.uv]
# 依存関係を追加する際に下限バージョンを自動的に追加
add-default-lower-bound = true

# 依存関係を追加する際に上限バージョンを自動的に追加
add-default-upper-bound = false

# キャッシュディレクトリの場所を指定
cache-dir = "~/.cache/uv"
```

#### インデックス設定

代替パッケージインデックスを設定できます：

```toml
[[tool.uv.index]]
url = "https://pypi.org/simple"
name = "pypi"

[[tool.uv.index]]
url = "https://my-private-index.example.com/simple"
name = "private"
username = "${PRIVATE_INDEX_USERNAME}"
password = "${PRIVATE_INDEX_PASSWORD}"
```

#### 依存関係のオーバーライド

特定の依存関係のバージョン制約をオーバーライドできます：

```toml
[tool.uv.override-dependencies]
pydantic = ">=1.0,<3"
```

#### キャッシュキーのカスタマイズ

ローカルパッケージのキャッシュキーをカスタマイズできます：

```toml
[tool.uv]
cache-keys = [
    { file = "requirements.txt" },
    { git = { commit = true } }
]
```

#### 環境の制限

ユニバーサル解決時に考慮する環境を制限できます：

```toml
[tool.uv]
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'"
]
```

#### 依存関係メタデータの提供

ビルドが難しいパッケージのメタデータを静的に提供できます：

```toml
[[tool.uv.dependency-metadata]]
name = "complex-package"
version = "1.0.0"
requires-dist = ["numpy>=1.20.0", "scipy>=1.7.0"]
```

## トラブルシューティング

uvを使用する際に発生する可能性のある一般的な問題とその解決策を紹介します。

### 依存関係の解決エラー

#### 問題: 依存関係の競合

```
error: Failed to resolve dependencies: Cannot satisfy dependencies for 'package-a' and 'package-b'
```

**解決策**:
1. `--resolution lowest`または`--resolution lowest-direct`を試す
2. 依存関係のオーバーライドを使用する
3. 競合している依存関係のバージョンを明示的に指定する

```bash
# オーバーライドを使用
uv pip compile --override overrides.txt requirements.in

# または、pyproject.tomlに追加
# [tool.uv.override-dependencies]
# conflicting-package = ">=1.0,<3"
```

#### 問題: プレリリースバージョンが必要

```
error: No matching distribution found for package>=1.0
```

**解決策**:
プレリリースバージョンを許可する

```bash
uv pip compile --prerelease allow requirements.in
```

### キャッシュの問題

#### 問題: 古いバージョンがインストールされる

**解決策**:
キャッシュを更新または無視する

```bash
# キャッシュを更新
uv sync --refresh

# 特定のパッケージのキャッシュを更新
uv sync --refresh-package problematic-package

# 既存のインストールを無視
uv sync --reinstall
```

#### 問題: キャッシュが破損している

**解決策**:
キャッシュをクリアする

```bash
uv cache clean
```

### Pythonバージョンの問題

#### 問題: 必要なPythonバージョンが見つからない

```
error: No Python installation found matching: Python 3.10
```

**解決策**:
必要なPythonバージョンをインストールする

```bash
uv python install 3.10
```

#### 問題: 互換性のないPythonバージョン

```
error: Package requires Python >=3.9, but current Python is 3.8.10
```

**解決策**:
互換性のあるPythonバージョンを使用する

```bash
uv run --python 3.9 example.py
```

### ビルドの問題

#### 問題: ビルド依存関係が見つからない

```
error: Building wheel for package failed: Could not find required build dependency
```

**解決策**:
ビルド依存関係を明示的にインストールする

```bash
# ビルド依存関係を含める
uv pip install package --build-include dependency
```

#### 問題: C拡張モジュールのビルドエラー

**解決策**:
1. 必要なコンパイラとビルドツールがインストールされていることを確認する
2. バイナリホイールが利用可能な場合は、それを使用する

```bash
# バイナリホイールを優先
uv pip install package --no-build
```

## パフォーマンス最適化

uvは非常に高速ですが、さらにパフォーマンスを最適化するためのテクニックを紹介します。

### キャッシュの最適化

1. **キャッシュの場所**: キャッシュディレクトリが高速なストレージ（SSDなど）にあることを確認します。

   ```toml
   # pyproject.toml
   [tool.uv]
   cache-dir = "/path/to/fast/storage/.cache/uv"
   ```

2. **定期的なキャッシュのプルーニング**: 未使用のキャッシュエントリを定期的に削除します。

   ```bash
   uv cache prune
   ```

3. **CI環境でのキャッシュ最適化**: CI環境では、ソースからビルドされたホイールのみをキャッシュします。

   ```bash
   uv cache prune --ci
   ```

### 依存関係解決の最適化

1. **ロックファイルの使用**: 依存関係の解決を毎回行わないようにロックファイルを使用します。

   ```bash
   # ロックファイルを作成
   uv lock
   
   # ロックファイルを使用して環境を更新
   uv sync
   ```

2. **必要な環境のみを解決**: ユニバーサル解決時に考慮する環境を制限します。

   ```toml
   # pyproject.toml
   [tool.uv]
   environments = [
       "sys_platform == 'darwin'",
       "sys_platform == 'linux'"
   ]
   ```

### インストールの最適化

1. **並列インストール**: uvは自動的に並列インストールを行いますが、大規模なプロジェクトでは特に効果的です。

2. **最小限の依存関係**: 必要最小限の依存関係のみを含めることで、インストール時間を短縮します。

   ```bash
   # 開発依存関係を分離
   uv add --dev dev-only-package
   ```

3. **バイナリホイールの使用**: ソースからのビルドを避けるためにバイナリホイールを優先します。

   ```bash
   uv pip install package --no-build
   ```

### 大規模プロジェクトでのパフォーマンス

1. **ワークスペースの使用**: 大規模なプロジェクトではワークスペースを使用して、共通の依存関係を共有します。

2. **選択的な同期**: 必要なパッケージのみを同期します。

   ```bash
   uv sync --package specific-package
   ```

3. **キャッシュキーの最適化**: ローカルパッケージのキャッシュキーを最適化して、不要な再ビルドを避けます。

   ```toml
   # pyproject.toml
   [tool.uv]
   cache-keys = [
       { file = "pyproject.toml" },
       { file = "src/**/*.py" }
   ]
   ```

## 実際のユースケース

uvの実際の使用例を紹介します。これらの例は、uvの機能を活用して様々なタイプのPythonプロジェクトを効率的に管理する方法を示しています。

### Webアプリケーション開発

Flaskを使用したWebアプリケーションの開発例：

```bash
# プロジェクトの作成
uv init flask-app
cd flask-app

# 依存関係の追加
uv add flask flask-sqlalchemy flask-migrate python-dotenv

# 開発依存関係の追加
uv add --dev pytest pytest-flask black mypy

# 開発サーバーの実行
uv run -- flask run --debug

# テストの実行
uv run -- pytest

# コードのフォーマット
uv run -- black .
```

### データサイエンスプロジェクト

データ分析とモデル開発のためのプロジェクト：

```bash
# プロジェクトの作成
uv init data-science-project
cd data-science-project

# 依存関係の追加
uv add numpy pandas matplotlib scikit-learn jupyter

# Jupyter Notebookの起動
uv run -- jupyter notebook

# スクリプトの実行
uv run data_processing.py

# 特定のPythonバージョンでの実行
uv run --python 3.10 model_training.py
```

### マイクロサービスアーキテクチャ

複数のマイクロサービスを含むワークスペースの管理：

```bash
# ワークスペースの作成
mkdir microservices
cd microservices

# ワークスペース設定
cat > pyproject.toml << EOF
[tool.uv.workspace]
members = ["services/*"]
EOF

# サービスの作成
mkdir -p services/auth
cd services/auth
uv init --name auth-service

# 依存関係の追加
uv add fastapi uvicorn pyjwt

# ワークスペースルートに戻る
cd ../..

# 別のサービスの作成
mkdir -p services/api
cd services/api
uv init --name api-service

# 依存関係の追加（ワークスペース内の他のパッケージに依存）
uv add fastapi uvicorn auth-service

# ワークスペース全体の依存関係を解決
cd ../..
uv lock
uv sync

# 特定のサービスを実行
uv run --package auth-service -- uvicorn auth_service.main:app --reload
```

### CI/CD自動化

GitHub Actionsを使用した継続的インテグレーションと継続的デリバリー：

```yaml
# .github/workflows/ci.yml
name: CI/CD

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11']

    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Install uv
      run: curl -LsSf https://astral.sh/uv/install.sh | sh
    
    - name: Cache dependencies
      uses: actions/cache@v3
      with:
        path: ~/.cache/uv
        key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml') }}-${{ hashFiles('**/uv.lock') }}
        restore-keys: |
          ${{ runner.os }}-uv-
    
    - name: Install dependencies
      run: uv sync
    
    - name: Lint
      run: |
        uv run -- ruff check .
        uv run -- black --check .
        uv run -- mypy .
    
    - name: Test
      run: uv run -- pytest --cov=src
    
    - name: Build package
      run: uv build
    
    - name: Publish package
      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
      run: uv publish --repository pypi
      env:
        PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
```

### ライブラリ開発

Pythonライブラリの開発と公開：

```bash
# プロジェクトの作成
uv init my-library
cd my-library

# 依存関係の追加
uv add pydantic

# 開発依存関係の追加
uv add --dev pytest black mypy build twine

# 最低バージョンでのテスト
uv lock --resolution lowest
uv sync
uv run -- pytest

# パッケージのビルド
uv build

# パッケージの公開
uv publish
```

### スクリプト自動化

依存関係を持つ単一ファイルスクリプトの作成と実行：

```bash
# スクリプトの作成
uv init --script data_processor.py

# 依存関係の追加
uv add --script data_processor.py pandas requests

# スクリプトの実行
uv run data_processor.py input.csv output.csv

# 依存関係のロック
uv lock --script data_processor.py
```

これらの実際のユースケースは、uvの様々な機能を活用して異なるタイプのPythonプロジェクトを効率的に管理する方法を示しています。

## TDDでの使用方法

uvは、テスト駆動開発（TDD）ワークフローをサポートするための機能を提供します。

### テスト環境のセットアップ

```bash
# テスト用の新しいプロジェクトを作成
uv init my-project
cd my-project

# テスト依存関係を追加
uv add --dev pytest pytest-cov
```

### テストの実行

```bash
# プロジェクト環境でテストを実行
uv run -- pytest

# カバレッジレポートを生成
uv run -- pytest --cov=my_package
```

### 異なる環境でのテスト

```bash
# 特定のPythonバージョンでテストを実行
uv run --python 3.10 -- pytest

# 最低バージョンの依存関係でテスト
uv lock --resolution lowest
uv sync
uv run -- pytest
```

### CI/CDパイプラインでの使用

```bash
# 依存関係をインストール
uv pip sync requirements.txt

# テストを実行
uv run -- pytest

# キャッシュを最適化
uv cache prune --ci
```

## 環境管理のベストプラクティス

### プロジェクト構造

推奨されるプロジェクト構造：

```
my-project/
├── .venv/                  # 仮想環境（自動生成）
├── .python-version         # デフォルトのPythonバージョン
├── pyproject.toml          # プロジェクトメタデータと依存関係
├── uv.lock                 # ロックファイル（自動生成）
├── README.md               # プロジェクトの説明
├── src/                    # ソースコード
│   └── my_package/
│       ├── __init__.py
│       └── ...
└── tests/                  # テスト
    ├── __init__.py
    └── ...
```

### 依存関係管理のベストプラクティス

1. **下限バージョンを指定する**：依存関係に下限バージョンを指定することで、互換性の問題を防ぎます。

   ```bash
   uv add 'requests>=2.28.0'
   ```

2. **開発依存関係を分離する**：開発専用の依存関係は`--dev`フラグを使用して追加します。

   ```bash
   uv add --dev pytest black mypy
   ```

3. **ロックファイルをバージョン管理に含める**：`uv.lock`ファイルをバージョン管理に含めることで、すべての開発者が同じ依存関係バージョンを使用できます。

4. **定期的に依存関係を更新する**：セキュリティ修正や機能改善を取り込むために、定期的に依存関係を更新します。

   ```bash
   uv lock --upgrade
   ```

5. **最低バージョンでテストする**：ライブラリを開発する場合、宣言された下限バージョンが正しいことを確認するために、最低バージョンでテストします。

   ```bash
   uv lock --resolution lowest
   uv sync
   uv run -- pytest
   ```

### 仮想環境の管理

uvは標準的な`.venv`ディレクトリに仮想環境を作成するため、従来のPython仮想環境と同じ方法でアクティベーションや管理ができます。

#### 仮想環境のアクティベーション

uvで作成した仮想環境は、標準的な方法でアクティベーションできます：

```bash
# macOSとLinux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
```

アクティベーション後は、`python`や`pip`などのコマンドが仮想環境のものを参照します：

```bash
# アクティベーション後、直接Pythonコマンドを実行可能
python -m pytest

# インストールされたツールも直接実行可能
black .
ruff check .
```

#### 仮想環境の非アクティベーション

仮想環境を非アクティベーションするには：

```bash
deactivate
```

#### 仮想環境の再作成

仮想環境に問題がある場合は、削除して再作成できます：

```bash
# 仮想環境を削除
rm -rf .venv  # macOSとLinux
# または
rmdir /s /q .venv  # Windows

# 仮想環境を再作成
uv venv
uv sync
```

#### 仮想環境を使わない実行

仮想環境をアクティベーションせずにコマンドを実行する場合は、`uv run`を使用します：

```bash
# 仮想環境をアクティベーションせずにコマンドを実行
uv run -- pytest
uv run -- black .
```

### 複数のPythonバージョンでの開発

1. **必要なPythonバージョンをインストール**：

   ```bash
   uv python install 3.9 3.10 3.11 3.12
   ```

2. **特定のバージョンをプロジェクトに固定**：

   ```bash
   uv python pin 3.11
   ```

3. **異なるバージョンでテスト**：

   ```bash
   uv run --python 3.9 -- pytest
   uv run --python 3.10 -- pytest
   uv run --python 3.11 -- pytest
   uv run --python 3.12 -- pytest
   ```

### CI/CD統合

GitHub Actionsの例：

```yaml
name: Test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']

    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Install uv
      run: curl -LsSf https://astral.sh/uv/install.sh | sh
    
    - name: Cache dependencies
      uses: actions/cache@v3
      with:
        path: ~/.cache/uv
        key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml') }}-${{ hashFiles('**/uv.lock') }}
        restore-keys: |
          ${{ runner.os }}-uv-
    
    - name: Install dependencies
      run: uv sync
    
    - name: Run tests
      run: uv run -- pytest
    
    - name: Optimize cache
      run: uv cache prune --ci
```

これらのベストプラクティスを活用することで、uvを使用したPythonプロジェクトの管理と開発を効率化できます。