Python uv完全解説

1. uvとは何か

uvはAstralが開発している、Rust製の高速なPythonパッケージ・プロジェクト管理ツールです。

公式ドキュメントでは、uvは pip、pip-tools、pipx、poetry、pyenv、virtualenv などの役割をまとめて置き換えられるツールとして説明されています。初心者目線では、「Pythonプロジェクトを作る」「ライブラリを入れる」「仮想環境を用意する」「コマンドを実行する」を、できるだけ少ない手順で扱うための道具と考えると入りやすいです。

flowchart LR
  U["uv"] --> P["Python本体の管理"]
  U --> V["仮想環境 .venv"]
  U --> D["依存関係 pyproject.toml"]
  U --> L["ロックファイル uv.lock"]
  U --> R["コマンド実行 uv run"]
  U --> T["CLIツール実行 uvx / uv tool"]
    

2. uvが解決すること

Python開発では、パッケージ、仮想環境、Pythonバージョン、ロックファイルが別々の話として出てきます。uvはそれらをひとつの操作体系にまとめます。

3. まず押さえるファイル

uvのプロジェクトでは、pyproject.toml、.venv、uv.lock の役割を分けて理解すると全体像が見えます。

flowchart TD
  Init["uv init"] --> Py["pyproject.toml"]
  Init --> Ver[".python-version"]
  Add["uv add requests"] --> Py
  Run["uv run main.py"] --> Venv[".venv"]
  Run --> Lock["uv.lock"]
  Sync["uv sync"] --> Venv
  Lock --> Sync
    

4. インストールと確認

Windowsでは公式のPowerShell用インストーラーが用意されています。macOSやLinuxではシェルスクリプト、Homebrew、pipなど複数の方法があります。

Windows

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

macOS / Linux

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

インストール確認

uv --version
uv help

5. 最初のプロジェクトを作る

uvの基本形は、作成、追加、実行、同期です。まずはこの4つだけで十分です。

新しいプロジェクトを作る

uv init hello-uv
cd hello-uv

uv init を実行すると、pyproject.toml やサンプルの main.py などが作られます。

プログラムを実行する

uv run main.py

uv run は、プロジェクトの環境を確認し、必要なら .venv や uv.lock を用意してからコマンドを実行します。

ライブラリを追加する

uv add requests

依存関係は pyproject.toml に追加され、実際の解決結果は uv.lock に記録されます。手で pip install するよりも、プロジェクトの状態がファイルに残りやすいのが利点です。

依存関係を同期する

uv sync

別PCでリポジトリを取得した後や、チームメンバーが依存関係を追加した後は uv sync で環境をそろえます。

6. よく使うコマンド一覧

最初からすべて覚える必要はありません。日常的にはプロジェクト系コマンドを中心に使います。

7. pip・venvとの違い

uvはpipやvenvを否定するというより、よく使う作業をまとめて扱いやすくする道具です。

8. 実務での基本ワークフロー

個人開発でもチーム開発でも、依存関係をファイルに残し、実行時はuvに環境をそろえてもらう流れが基本です。

新規プロジェクト

uv init my-app
cd my-app
uv python pin 3.12
uv add fastapi
uv add --dev pytest
uv run python main.py

既存プロジェクトを取得した後

git clone https://example.com/my-app.git
cd my-app
uv sync
uv run pytest

一時的にツールを実行する

uvx ruff check .
uvx black .

uvx は uv tool run の短い別名です。プロジェクトに依存関係として追加するほどではないCLIツールを、さっと実行したいときに便利です。

9. lockとsyncの考え方

uvでは、依存関係を「解決する」ことと「環境へ入れる」ことを分けて考えます。

公式ドキュメントでは、uv run のようなコマンドは実行前に自動でlockとsyncを行い、環境を最新状態に保つと説明されています。普段は自動に任せてもよいですが、CIやチーム開発では uv sync を明示すると状態をそろえやすいです。

uv lock
uv sync
uv run pytest

10. どんな人に向いているか

uvは、これからPython開発を始める人にも、既存のpip/venv運用を軽くしたい人にも向いています。

11. 初心者がつまずきやすい点

uvは便利ですが、pipと同じ感覚で使いすぎると、プロジェクト管理の利点を逃すことがあります。

12. まとめ

uvは、Python開発の「環境構築が面倒」「何をGitに入れるのか分からない」「pipとvenvの組み合わせで迷う」を減らすための強力な入口です。

参考ソース

• uv公式ドキュメント: Introduction
• uv公式ドキュメント: Features
• uv公式ドキュメント: Working on projects
• uv公式ドキュメント: Project structure and files
• uv公式ドキュメント: Locking and syncing
• uv公式ドキュメント: CLI Reference
• astral-sh/uv GitHubリポジトリ