uv

uv

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

uv を使う場面

Python の作業では必ず uv を使用してください。特に、次のものがある場合に使用します。

• uv.lock ファイル
• requirements* ファイル内の uv ヘッダー（例：「このファイルは uv によって自動生成されました」）

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

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

適切なワークフローを選ぶ

スクリプト

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

主なコマンド：

uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add dependencies inline to the script

プロジェクト

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

主なコマンド：

uv init                   # Create new project
uv add requests           # Add dependency
uv remove requests        # Remove dependency
uv sync                   # Install from lockfile
uv run <command>          # Run commands in environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version

ツール

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

主なコマンド：

uvx <tool> <args>            # Run a tool without installation
uvx <tool>@<version> <args>  # Run a specific version of a tool

重要：

• 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

# Platform independent resolution
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 を使用しない

# Bad
pip install requests

# Good
uv add requests

python を直接実行しない

# Bad
python script.py

# Good
uv run script.py

# Bad
python -c "..."

# Good
uv run python -c "..."

# Bad
python3.12 -c "..."

# Good
uvx [email protected] -c "..."

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

# Bad
python -m venv .venv
source .venv/bin/activate

# Good
uv run <command>

ドキュメント

詳しくは、公式ドキュメントをお読みください。

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

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