第2章 uv によるプロジェクト管理と実行

uv は、Astral 社が開発したオープンソースの高速 Python パッケージマネージャーです。

従来の pip や Poetry、pyenv などの機能を包括し、依存関係の解決、仮想環境の構築、パッケージのインストール、コマンド実行を驚異的な速度で実行します。本章では、uv を使ったプロジェクトのセットアップと日常的な操作手順を解説します。

2.1 uv の主な特徴

uv には、現代の開発者が求める強力な特徴が数多く備わっています。

圧倒的な高速性: Rust 言語で開発されており、C++ や Python 製の従来ツールに比べ、依存関係の解決やダウンロードが最大 10〜100 倍高速です。
グローバルキャッシュ: ダウンロードしたホイール（wheel）ファイルをマシン全体でキャッシュ・共有（ハードリンクやコピー）するため、複数プロジェクト間での重複ダウンロードを防ぎ、ディスク容量と時間を節約します。
決定論的なロックファイル: uv.lock を自動生成し、クロスプラットフォーム（Linux / macOS / Windows）で完全に一致する依存関係を再現します。
Python バージョンの自動管理: マシンに指定の Python がインストールされていない場合でも、uv 自身が必要な Python バージョンを自動的に取得して利用できます。
仮想環境のアクティベーション不要: uv run を介して実行することで、開発者が手動で source .venv/bin/activate を実行する手間を省きます。

2.2 uv のインストール

uv はスタンドアロンのバイナリとして配布されています。プラットフォームに応じたコマンドで簡単にインストールできます。

Linux / macOS

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

Windows (PowerShell)

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

インストール後、以下のコマンドで正しく導入されたか確認します：

uv --version

2.3 プロジェクトの新規作成 (uv init)

新しい Python プロジェクトを開始するには、uv init コマンドを使用します。

# 新規ディレクトリを作成して初期化
uv init my-app
cd my-app

既存のディレクトリ内で初期化する場合は、引数なしで実行します：

uv init

初期化によって生成されるファイル

uv init を実行すると、標準で以下のファイル群が作成されます：

pyproject.toml: プロジェクト設定および依存関係の定義ファイル。
.python-version: 使用する Python バージョンを明記したファイル。
README.md: プロジェクトの説明用ドキュメント。
main.py（または hello.py）: サンプルのエントリーポイントファイル。
.gitignore: Git 管理対象から外すファイル（.venv/ 等）の除外定義。

2.4 パッケージの依存関係管理 (uv add / uv remove)

外部ライブラリをプロジェクトに追加・削除する操作は、uv add および uv remove で直感的に行えます。

パッケージの追加

たとえば、HTTP 通信ライブラリ httpx を追加する場合：

uv add httpx

このコマンドを実行すると、以下の処理が自動的に行われます：

pyproject.toml の dependencies に httpx>=0.27.0 のようにパッケージが追記されます。
依存関係の整合性が解決され、uv.lock が作成・更新されます。
ローカルの仮想環境（.venv/）が自動構築され、パッケージがインストールされます。

開発用依存関係（Dev Dependencies）の追加

テストライブラリ（pytest）やリンターなど、開発時のみ必要なパッケージは --dev フラグを付けて追加します：

uv add --dev pytest

これは pyproject.toml 内の [dependency-groups]（または [project.optional-dependencies]）に記録され、本番デプロイ用の依存関係と明確に分離されます。

パッケージの削除

不要になったパッケージは uv remove で削除します：

uv remove httpx
uv remove --dev pytest

2.5 プロジェクトの実行 (uv run)

uv を利用する最大の利点の一つが uv run コマンドです。

従来は、仮想環境を有効化（アクティベート）した上で python main.py を実行する必要がありました。uv run を使うと、仮想環境の有無やパッケージの同期状態を自動検証し、常に最新の隔離環境でスクリプトやコマンドを実行してくれます。

# アプリケーションの実行
uv run main.py

# インストールした CLI コマンドの実行
uv run pytest

手動で activate コマンドを叩く必要がないため、スクリプト実行時や CI 環境でのミスを根本から防ぐことができます。

2.6 依存関係の完全同期 (uv sync)

Git リポジトリからプロジェクトをクローンしてきた直後や、他のメンバーが更新した uv.lock をローカル環境に反映したい場合は、uv sync を実行します。

uv sync

uv sync は、uv.lock に記述された正確なバージョン構成とローカルの .venv の状態を比較し、不足しているパッケージの追加や、不要になった古いパッケージの削除を一括して行います。

2.7 スクリプト単体でのインライン依存関係実行

uv は、プロジェクト構造を作らずに単一の Python スクリプトを実行したい場合にも威力を発揮します。

スクリプトファイルの冒頭に PEP 723 準拠のインラインメタデータを記述しておくと、uv run は一時的な仮想環境を作成し、必要なライブラリを自動でインストールして即座に実行します。

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "httpx",
#     "rich",
# ]
# ///

import httpx
from rich import print

response = httpx.get("https://httpbin.org/json")
print(response.json())

実行は以下のコマンドのみです：

uv run fetch.py

このように、uv を使うことで、本格的なアプリケーション開発から手軽な自動化スクリプトまで、統一的で快適な環境を実現できます。

Keyboard shortcuts