uv

uvは非常に高速なPythonパッケージおよびプロジェクトマネージャーです。pip、pip-tools、pipx、pyenv、virtualenv、poetryなどを置き換えます。

uvを使用すべき場合

Pythonの作業には常にuvを使用してください。特に以下が見つかった場合：

• uv.lock ファイル
• requirements* ファイル内のuvヘッダー（例：「This file was autogenerated by uv」）

他のツールで管理されているプロジェクトではuvを使用しないでください：

• Poetryプロジェクト（poetry.lock ファイルで識別可能）
• PDMプロジェクト（pdm.lock ファイルで識別可能）

適切なワークフローの選択

スクリプト

使用場面： 単一のPythonファイルとスタンドアロンスクリプトを実行する場合。

主要コマンド：

uv run script.py                      # スクリプトを実行
uv run --with requests script.py      # 追加パッケージを含めて実行
uv add --script script.py requests    # 依存関係をスクリプトにインラインで追加

プロジェクト

使用場面： pyproject.toml または uv.lock が存在する場合。

主要コマンド：

uv init                   # 新しいプロジェクトを作成
uv add requests           # 依存関係を追加
uv remove requests        # 依存関係を削除
uv sync                   # ロックファイルからインストール
uv run <command>          # 環境内でコマンドを実行
uv run python -c ""       # プロジェクト環境内でPythonを実行
uv run -p 3.12 <command>  # 特定のPythonバージョンで実行

ツール

使用場面： コマンドラインツール（例：ruff、ty、pytest）をインストールせずに実行する場合。

主要コマンド：

uvx <tool> <args>            # インストールせずにツールを実行
uvx <tool>@<version> <args>  # 特定のバージョンのツールを実行

重要：

• uvx はパッケージ名でPyPIからツールを実行します。これは安全でない可能性があります。よく知られたツールのみを実行してください。
• uv tool install はユーザーが明確に要求した場合のみ使用してください。

Pipインターフェース

使用場面： requirements.txt を使用したレガシーワークフローまたは手動環境管理。uv.lock が存在しない場合。

主要コマンド：

uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

# プラットフォーム非依存の解決
uv pip compile --universal requirements.in -o requirements.txt

重要：

• 明確に必要でない限り、pipインターフェースを使用しないでください。
• 新しい requirements.txt ファイルを導入しないでください。
• 新規プロジェクトでは uv init を優先してください。

他のツールからの移行

pyenv → uv python

pyenv install 3.12       → uv python install 3.12
pyenv versions           → uv python list --only-installed
pyenv local 3.12         → uv python pin 3.12
pyenv global 3.12        → uv python install 3.12 --default

pipx → uvx

pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list

pip と pip-tools → uv pip

pip install package      → uv pip install package
pip install -r req.txt   → uv pip install -r req.txt
pip freeze               → uv pip freeze
pip-compile req.in       → uv pip compile req.in
pip-sync req.txt         → uv pip sync req.txt
virtualenv .venv         → uv venv

一般的なパターン

uvプロジェクトではpipを使用しないでください

# 悪い例
pip install requests

# 良い例
uv add requests

pythonを直接実行しないでください

# 悪い例
python script.py

# 良い例
uv run script.py

# 悪い例
python -c "..."

# 良い例
uv run python -c "..."

# 悪い例
python3.12 -c "..."

# 良い例
uvx python@3.12 -c "..."

uvプロジェクトで環境を手動で管理しないでください

# 悪い例
python -m venv .venv
source .venv/bin/activate

# 良い例
uv run <command>

ドキュメント

詳細な情報については、公式ドキュメントを参照してください：

• https://docs.astral.sh/uv/llms.txt

ドキュメントには、これらの各ワークフローの個別ページへのリンクがあります。