uv

uv（Python）

リポジトリに uv.lock がある場合、ドキュメント／Makefile で uv に言及している場合、または uv で作成された .venv をすでに使用している場合は、Python の依存関係と環境の管理に uv をデフォルトのツールとして使用してください。

簡単な判断ルール

• リポジトリに uv.lock と pyproject.toml がある場合：uv 管理のプロジェクトとして扱います。
• リポジトリに requirements.txt だけがある場合：高速なインストールには uv pip を使用できます。
• リポジトリで明示的に uv pip を使用している場合を除き、pip を直接使うよりプロジェクトコマンド（uv add/remove/sync/run/lock）を優先してください。

インストール（必要な場合）

利用できる場合は、パッケージ化されたインストール方法を優先してください。公式インストーラーを使用する場合は、事前に内容を確認し（シェルにそのままパイプするのは避けてください）、公式ドキュメントの最新の手順に従ってください。

# macOS/Linux (official installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell, official installer)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

一般的な操作

新しいプロジェクトを初期化する

uv init
# or
uv init my-project

仮想環境を作成／使用する

uv venv  # creates .venv

# If you need a specific version, match the project's declared requirement
# (e.g., pyproject.toml / CI config), not an arbitrary latest version.
uv venv --python 3.x

# optional activation (not required for uv commands)
source .venv/bin/activate  # macOS/Linux
# .venv\\Scripts\\activate   # Windows

依存関係を追加／削除する（pyproject.toml と uv.lock を更新）

uv add requests
uv add 'requests==2.31.0'
uv add -r requirements.txt

uv remove requests

ロックと同期（再現性のあるインストール）

uv lock   # (re)generate uv.lock
uv sync   # create/update .venv to match uv.lock

新しい変更を取り込んで uv.lock が変更された場合は、uv sync を実行してください。

プロジェクト環境内でコマンドを実行する

uv run python -m pytest -q
uv run python main.py
uv run ruff check .

高速な pip の代替として uv を使用する（requirements を使用するワークフロー）

uv venv
uv pip install -r requirements.txt
uv pip freeze
uv pip list

注意事項／落とし穴

• uv は通常、プロジェクトのルートにある .venv を自動検出して使用します。
• CI／コンテナでは uv pip install --system を見かけることがありますが、ローカル開発では仮想環境を優先してください。
• コマンドが依存関係を変更する場合は、uv.lock が正しく保たれるよう、uv add/remove/lock/sync を優先してください。