Pythonの環境構築は、長年多くのエンジニアを悩ませてきた課題です。

pip、venv、pyenv、poetry、pip-toolsなど、用途に応じて複数のツールを使い分ける必要があり、その複雑さや動作の遅さが開発のボトルネックとなることも少なくありませんでした。

しかし、Rust製の超高速ツールであるuvの登場により、Pythonのエコシステムは劇的な進化を遂げました。

uvは、パッケージのインストールだけでなく、Python自体のバージョン管理や仮想環境の構築、プロジェクト管理のすべてを単一のバイナリで完結させます。

本記事では、uvの導入方法から具体的な使い方、さらには既存ツールとの違いまでを網羅的に解説します。

目次 [ close ]
  1. uvとは？次世代のPython管理ツール
    1. uvが解決する課題
    2. uvの圧倒的なパフォーマンス
  2. uvのインストール方法
    1. macOS / Linuxの場合
    2. Windowsの場合
    3. インストールの確認
  3. uvでのプロジェクト作成と基本操作
    1. 1. プロジェクトの初期化
    2. 2. Pythonバージョンの管理
    3. 3. パッケージの追加と管理
    4. 4. プログラムの実行
  4. uvの高度な機能
    1. パッケージの同期と一括インストール
    2. ツールの実行（uvx）
    3. ワークスペース機能
  5. Pythonスクリプトの作成と実行例
    1. サンプルコードの作成
    2. パッケージのインストールと実行
  6. 既存ツール（Poetry等）からの移行
    1. 移行のメリット
    2. CI/CDでの活用
  7. uvを使用する際の注意点
  8. まとめ

uvとは？次世代のPython管理ツール

uvは、静的解析ツール「Ruff」の開発で知られるAstral社によって開発された、RustベースのPythonプロジェクトマネージャーです。

その最大の特徴は、既存のツールを圧倒する「実行速度」と、複数のツールに分散していた機能を「一つに集約」した利便性にあります。

uvが解決する課題

従来のPython開発では、以下のようなツールを組み合わせて使用するのが一般的でした。

カテゴリ従来のツールuvでの対応
パッケージ管理pip, pip-toolsuv pip / uv add
環境分離（仮想環境）venv, virtualenvuv venv / 自動管理
Pythonバージョン管理pyenv, condauv python
プロジェクト管理poetry, pdmuv init / uv sync
スクリプト実行pipxuv run / uvx

このように、uvはPython開発に必要なほぼすべての機能をカバーしています。

これにより、開発者は複数のツールをインストールして設定を管理する手間から解放されます。

uvの圧倒的なパフォーマンス

uvはRustで記述されており、並列処理や洗練されたキャッシュメカニズムを駆使しています。

特にパッケージのインストール速度は、従来のpipと比較して10倍から100倍近く高速になることも珍しくありません。

また、グローバルなキャッシュを利用するため、一度ダウンロードしたパッケージを別プロジェクトで再利用する際、ディスク容量を節約しつつ一瞬でインストールが完了します。

uvのインストール方法

uvは単一の実行バイナリとして提供されているため、インストールは非常に簡単です。

OSごとの主要なインストールコマンドを紹介します。

macOS / Linuxの場合

ターミナルで以下のcurlコマンドを実行します。

Shell
# インストールスクリプトの実行
curl -LsSf https://astral.sh/uv/install.sh | sh

Windowsの場合

PowerShellを開き、以下のコマンドを実行します。

PowerShell
# PowerShell用のインストールスクリプト
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

インストールの確認

インストール完了後、以下のコマンドを入力してバージョンが表示されれば成功です。

Shell
# バージョンの確認
uv --version
実行結果
uv 0.5.x (xxxxxxxxx 202x-xx-xx)

uvでのプロジェクト作成と基本操作

uvを使用したプロジェクト管理のワークフローは、非常に洗練されています。

ここでは、プロジェクトの初期化からパッケージの追加、プログラムの実行までの流れを説明します。

1. プロジェクトの初期化

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

Shell
# プロジェクトディレクトリを作成して移動
mkdir my-python-project
cd my-python-project

# uvプロジェクトとして初期化
uv init

このコマンドを実行すると、以下のファイルが自動生成されます。

  • pyproject.toml：プロジェクトの設定や依存関係を記述するファイル。
  • hello.py：サンプルコード。
  • .python-version：使用するPythonのバージョンを指定するファイル。

2. Pythonバージョンの管理

uvは、システムにインストールされていないPythonバージョンを自動的にダウンロードして管理する機能を持っています。

Shell
# 特定のバージョンをプロジェクトに関連付ける
uv python pin 3.12

# 利用可能なPythonの一覧を表示
uv python list

uv python installを実行することで、特定のバージョンを個別にインストールすることも可能です。

3. パッケージの追加と管理

プロジェクトにライブラリを追加するには、uv addを使用します。

Shell
# requestsライブラリを追加
uv add requests

このコマンドを実行すると、uvは即座に仮想環境（.venv）を作成し、ライブラリをインストールします。

また、pyproject.tomlが更新されるとともに、詳細な依存関係を固定するuv.lockファイルが生成されます。

開発時のみ必要なパッケージを追加する場合

テストツールやフォーマッタなど、開発環境でのみ必要なパッケージは--devフラグを付けて追加します。

Shell
# pytestを開発用依存関係として追加
uv add --dev pytest

4. プログラムの実行

uvで管理されている環境でスクリプトを実行するには、uv runを使用します。

Shell
# hello.pyを実行
uv run hello.py

uv runの素晴らしい点は、仮想環境を自動的にアクティベートして実行してくれることです。

開発者が手動でsource .venv/bin/activateを叩く必要はありません。

また、簡単なスクリプトであれば、依存関係を記述したコメントをファイル冒頭に書くだけで、インラインで実行環境を構築する機能（PEP 723準拠）もサポートしています。

uvの高度な機能

基本的な操作以外にも、uvには実務で役立つ強力な機能が備わっています。

パッケージの同期と一括インストール

チーム開発において、他のメンバーが更新したuv.lockの内容を自分の環境に反映させるには、uv syncを使用します。

Shell
# uv.lockに基づき、環境を完全に同期させる
uv sync

ツールの実行（uvx）

pipxのように、Pythonパッケージとして提供されているコマンドラインツールを、一時的な仮想環境で即座に実行したい場合はuvx（またはuv tool run）が便利です。

Shell
# ruffを一過性の環境で実行
uvx ruff check .

これにより、メインのプロジェクト環境を汚すことなく、最新のツールを試用することができます。

ワークスペース機能

大規模な開発において、複数のパッケージを一つのリポジトリで管理する「モノレポ（Monorepo）」構成をとることがあります。

uvのワークスペース機能を使えば、共通のロックファイルを保持しつつ、複数のサブプロジェクトを効率的に管理できます。

pyproject.tomlに以下のような記述を追加することで、ディレクトリを跨いだ依存関係の解決が可能になります。

TOML
[tool.uv.workspace]
members = ["packages/*"]

Pythonスクリプトの作成と実行例

ここでは、実際にuvを使用して外部ライブラリを活用するスクリプトを作成し、実行するまでの具体的な手順を示します。

サンプルコードの作成

まず、HTTPリクエストを送信してJSONデータを取得する簡単なプログラムを作成します。

Python
# main.py
import requests

def fetch_data():
    # 公開APIからデータを取得
    url = "https://jsonplaceholder.typicode.com/todos/1"
    response = requests.get(url)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Title: {data['title']}")
    else:
        print("Failed to fetch data")

if __name__ == "__main__":
    fetch_data()

パッケージのインストールと実行

次に、必要なライブラリを追加して実行します。

Shell
# ライブラリの追加
uv add requests

# スクリプトの実行
uv run main.py

実行すると、以下のような結果が得られます。

実行結果
Title: delectus aut autem

このように、uv addからuv runまでの流れが非常にスムーズであり、環境構築にかかる待ち時間がほとんどないことが実感できるはずです。

既存ツール（Poetry等）からの移行

現在Poetryを使用しているプロジェクトでも、uvへの移行は比較的スムーズに行えます。

uvは標準的なpyproject.tomlを解釈できるため、設定ファイルをそのまま活用しつつ、高速なロック・同期機能の恩恵を受けることができます。

移行のメリット

  1. インストールの高速化：Poetryで数分かかっていた依存解決が、uvなら数秒で終わるケースが多いです。
  2. 単一バイナリ：uv自体をインストールするのにPython環境を必要としないため、CI/CDパイプラインがシンプルになります。
  3. メモリ消費の削減：Rust実装のため、大規模な依存関係グラフの解決時もメモリ消費が抑えられます。

CI/CDでの活用

GitHub ActionsなどのCI環境でuvを使用する場合、公式のsetup-uvアクションを利用することで、爆速なビルド環境を構築できます。

YAML
# GitHub Actionsの例
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      uses: actions/checkout@v4
      uses: astral-sh/setup-uv@v1
      name: Install dependencies
        run: uv sync
      name: Run tests
        run: uv run pytest

uvを使用する際の注意点

非常に強力なuvですが、導入にあたっていくつか留意すべき点があります。

比較的新しいツールであること

uvは開発速度が非常に速く、頻繁にアップデートが行われます。

最新の機能を享受できる反面、破壊的な変更や挙動の調整が行われる可能性があるため、公式ドキュメントやリリースノートを定期的に確認することをお勧めします。

一部の古いパッケージとの相性

標準的なビルドシステム（setuptoolsやwheelなど）には対応していますが、極めて特殊なビルドプロセスを持つ古いパッケージでは稀にエラーが発生するケースがあります。

必要に応じてパッケージのビルド設定を見直すか、代替手段を検討してください。

独自のロックファイル形式

uv.lockはpoetry.lockとは互換性がありません。

チーム全体でuvに移行するか、あるいは標準的なrequirements.txtを書き出す運用を検討する必要があります。

まとめ

uvは、これまでのPython環境構築における「遅い」「複雑」「ツールの乱立」という三重苦を解決する画期的なツールです。

Rustによる圧倒的なスピードと、Pythonバージョン管理からパッケージ管理までを統合したスマートな操作性は、現代のPython開発において標準的な選択肢になりつつあります。

特に、新規プロジェクトを開始する際や、CI/CDの実行時間を短縮したい場合には、uvの導入が非常に大きなリターンをもたらします。

まずは個人の開発環境からuv initを試してみて、その快適さを体感してみてください。

Pythonのエコシステムは常に変化していますが、uvのような優れたツールの登場により、開発者は本来の目的である「コードを書くこと」により集中できるようになっています。

この記事を参考に、ぜひあなたのプロジェクトにもuvを取り入れて、ストレスのないPython開発ライフを送りましょう。