uvの使い方完全ガイド【インストールから応用まで】

新しいPythonプロジェクトを始める時、あなたはいつも何を感じますか？ 依存パッケージのインストールに何分もかかり、イライラした経験はありませんか？ あるいは、pip、pip-tools、virtualenv、poetryなど、複数のツールを使い分ける複雑さにうんざりしていませんか？

これまでのPython開発では、環境構築や依存解決に多くの時間が費やされてきました。 しかし、もしそれらの作業が劇的に高速化され、しかも一つのツールで完結するとしたらどうでしょう？ まるで魔法のように高速で、開発の初期段階から集中できる世界が実現します。

そんな未来を現実にするのが、今回ご紹介する「uv」です。uvは、あなたのPython開発ワークフローを一変させる可能性を秘めています。

uvとは — 30秒で分かる概要・誕生した背景

uvは、Rustで書かれた超高速なPythonパッケージおよびプロジェクトマネージャです。 従来のpipと比較して、10倍から100倍という驚異的な速度を実現します。 これにより、Python開発における依存解決やパッケージインストールが劇的に高速化されます。

uvの最大の特長は、その「統合性」にあります。pip、pip-tools、pipx、poetry、pyenv、virtualenvといった、これまで個別に利用されていた多くのツールの機能を一つに統合しました。 これにより、Python開発のワークフローが劇的にシンプルになります。 異なるツール間の連携や設定に悩む必要がなくなるでしょう。

uvは、Pythonの高速リンター/フォーマッターとして有名な「Ruff」の開発元であるAstral社によって生み出されました。 Pythonエコシステムにおける断片化とパフォーマンス問題への明確な解決策として誕生したのです。 高速なツール開発で実績のあるAstral社が、Pythonパッケージ管理の未来を切り開いています。

インストール方法 — OS別コマンド

uvのインストールは非常に簡単です。 公式では、スタンドアロンインストーラを推奨しています。 RustやPythonの環境がなくても導入できる点が魅力です。

macOS / Linuxの場合

以下のコマンドをターミナルで実行してください。

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

Windowsの場合

PowerShellで以下のコマンドを実行してください。

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

pipまたはpipxでインストールする場合

既存のPython環境にuvをパッケージとしてインストールすることも可能です。

# pipでインストール
pip install uv

# pipxでインストール
pipx install uv

uv自体のアップデート

スタンドアロンインストーラでuvをインストールした場合、以下のコマンドでuv自身を最新バージョンに更新できます。

uv self update

基本的な使い方 — 最低限これだけ知れば使えるコマンド3〜5個

uvを使い始めるために、まずはこれらのコマンドを覚えましょう。 プロジェクトの初期化からパッケージの管理、スクリプトの実行まで、基本的な開発ワークフローをカバーできます。

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

新しいPythonプロジェクトを始める際、プロジェクトディレクトリを作成し、uvの管理下におきます。 これにより、仮想環境や依存関係の管理がスムーズになります。

例えば、my-projectという新しいプロジェクトを作成する場合です。

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

# uvでプロジェクトを初期化
uv init

このコマンドを実行すると、現在のディレクトリに.venvという仮想環境が作成されます。 また、pyproject.tomlファイルが生成され、プロジェクトのメタデータが定義されます。

2. パッケージの追加: uv add

プロジェクトに新しいパッケージを追加する際に使います。uv addコマンドは、指定されたパッケージをインストールし、仮想環境に反映します。 同時に、pyproject.tomlにも依存関係が追記されます。

例えば、requestsパッケージを追加する場合です。

uv add requests

開発環境でのみ必要なパッケージ（テストフレームワークなど）は、--devオプションを付けて追加できます。

uv add pytest --dev

3. スクリプトの実行: uv run

プロジェクトの仮想環境内でスクリプトやコマンドを実行します。 これにより、システムグローバルなPython環境を汚染することなく、プロジェクト固有の依存関係を利用できます。

例えば、ruffがインストールされているプロジェクトで、ruff checkコマンドを実行する場合です。

uv run ruff check

Pythonスクリプトを実行する際は、次のようにします。

# my_script.py というファイルがある場合
uv run python my_script.py

4. 依存関係の同期: uv sync

pyproject.tomlファイルに記述された依存関係に基づいて、仮想環境を最新の状態に同期します。 これは、新しいパッケージが追加されたり、既存のパッケージのバージョンが変更されたりした際に使用します。 また、uv lockコマンドによって生成されるロックファイル（uv.lock）がある場合は、そのロックファイルに基づいて依存関係をインストールします。

uv sync

このコマンドは、依存関係の解決、ダウンロード、インストールを一貫して行います。 高速なため、頻繁に実行してもストレスがありません。

5. 依存関係のロック: uv lock

プロジェクトの依存関係を確定させ、uv.lockというファイルに書き出します。 このロックファイルには、すべての依存パッケージとその正確なバージョン、ハッシュ値などが記録されます。 これにより、チーム開発において、全員が同じ依存関係でプロジェクトを実行できることが保証されます。

uv lock

uv lockでロックファイルを生成した後、uv syncを実行することで、そのロックファイル通りの環境が構築されます。

便利な使い方・応用例 3選 — 実際の開発シーンに落とし込む

uvは単なる高速なpipではありません。 多岐にわたる機能で、開発のあらゆる側面をサポートします。 ここでは、実際の開発シーンで役立つ応用例を3つご紹介します。

応用例1: 単一ファイルスクリプトの依存管理

ちょっとしたスクリプトを実行する際にも、uvは非常に便利です。 スクリプトファイル内に依存関係を直接記述することで、その場で仮想環境を構築し、必要なパッケージをインストールして実行できます。 これは、pipxや一部のシェルスクリプトランナーの機能を代替します。

例えば、requestsを使ってウェブページを取得するスクリプトを作成する場合です。script.pyというファイルを作成し、先頭にコメント形式で依存関係を記述します。

# script.py
# This script requires the 'requests' library.
# dependencies: requests

import requests

def fetch_url(url):
    try:
        response = requests.get(url)
        response.raise_for_status()  # HTTPエラーがあれば例外を発生させる
        print(f"URL: {url}")
        print(f"Status Code: {response.status_code}")
        print(f"Content Length: {len(response.text)} bytes")
    except requests.exceptions.RequestException as e:
        print(f"Error fetching {url}: {e}")

if __name__ == "__main__":
    target_url = "https://example.com"
    fetch_url(target_url)

このスクリプトを実行するには、uv runを使います。uvが自動で依存関係を解決し、仮想環境を作成して実行してくれます。

uv run python script.py

初回実行時には依存解決とインストールが行われますが、2回目以降はキャッシュが効くため非常に高速です。

応用例2: 既存のrequirements.txtを高速に扱う

多くのPythonプロジェクトでは、依然としてrequirements.txtファイルが依存関係の管理に使われています。uvはpip互換のインターフェースを提供しており、既存のrequirements.txtファイルを驚異的な速度で処理できます。

例えば、既存のプロジェクトにrequirements.txtがある場合、uv pip installを使います。

# requirements.txt の例
# requests==2.32.3
# beautifulsoup4==4.12.3

# uvを使ってrequirements.txtからインストール
uv pip install -r requirements.txt

これはpip install -r requirements.txtと全く同じように機能しますが、実行速度は圧倒的に高速です。 既存のプロジェクトにuvを導入する際の最初のステップとして非常に有効です。

応用例3: Pythonバージョンのインストールと管理

uvは、pyenvのように複数のPythonバージョンをインストールし、切り替える機能も持っています。 これにより、プロジェクトごとに異なるPythonバージョンを使用する環境を簡単に構築できます。

利用可能なPythonバージョンを一覧表示します。

uv python list

特定のPythonバージョン（例えば3.11）をインストールします。

uv python install 3.11

プロジェクトで使用するPythonバージョンを指定します。 これにより、カレントディレクトリに.python-versionファイルが作成され、uvがそのバージョンを使用するようになります。

uv python use 3.11

uvが管理するPythonバージョンを削除することも可能です。

uv python uninstall 3.11

これらのコマンドにより、Pythonバージョンの管理もuv一つで完結できます。

他ツールとの組み合わせ — 相性のよいツールと組み合わせ方

uvは単体でも強力ですが、他のツールと組み合わせることでさらに真価を発揮します。 ここでは、特に相性の良いツールとその組み合わせ方を紹介します。

1. Ruffとの連携

uvと同じAstral社が開発しているRuffは、Pythonの高速リンターおよびフォーマッターです。 両者は非常に高い親和性を持っています。 uvの仮想環境内でRuffを実行することで、プロジェクト固有のRuff設定やバージョンでコード品質をチェックできます。

例えば、プロジェクトにRuffを追加し、コードチェックを実行する場合です。

# プロジェクトにruffを追加
uv add ruff --dev

# uv runを使ってruff checkを実行
uv run ruff check .

uv runを使うことで、プロジェクトの仮想環境にインストールされたRuffが確実に実行されます。 これにより、開発環境の一貫性が保たれます。

2. VS Codeでの快適な開発

Visual Studio Code（VS Code）は、Python開発で広く使われているエディタです。uvで作成された仮想環境は、VS CodeのPython拡張機能によって自動的に検出されます。 これにより、以下のメリットが得られます。

• 自動的な仮想環境の選択: プロジェクトを開くと、VS Codeが.venvディレクトリ内の仮想環境を自動で認識し、選択します。
• IntelliSenseの強化: 仮想環境にインストールされたパッケージに基づいて、コード補完や型ヒントが正確に機能します。
• 統合ターミナルでの利用: VS Codeの統合ターミナルでuvコマンドを直接実行でき、シームレスな開発体験が得られます。

特に設定は不要で、uv initで作成したプロジェクトをVS Codeで開くだけで恩恵を受けられます。

3. Dockerコンテナでの活用

Dockerを使ってPythonアプリケーションをコンテナ化する際、uvはそのビルドプロセスを劇的に高速化します。Dockerfile内でpip installの代わりにuv pip installを使用することで、コンテナイメージのビルド時間を短縮できます。

例えば、従来のDockerfileが以下のような場合です。

# Dockerfile (従来)
FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["python", "app.py"]

これをuvを使って最適化すると、以下のようになります。

# Dockerfile (uvを使用)
# uvのインストールは、Python環境がなくても実行できるスタンドアロンインストーラを使うのが効率的です。
FROM python:3.10-slim

# uvをインストール
RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
    && mv /root/.cargo/bin/uv /usr/local/bin/uv \
    && rm -rf /root/.cargo

WORKDIR /app

COPY requirements.txt .
# uvを使ってrequirements.txtからインストール
RUN uv pip install -r requirements.txt

COPY . .

CMD ["python", "app.py"]

uvのインストールステップは増えますが、その後のuv pip installの速度が圧倒的なため、全体のビルド時間が短縮されることが多いです。 特に、キャッシュが効きにくいCI/CD環境での効果は絶大です。

よくある設定・カスタマイズ — dotfilesや設定ファイルの例

uvはデフォルト設定でも十分高速ですが、いくつかの設定やカスタマイズで、さらに使いやすくできます。

1. プロジェクト設定ファイル pyproject.toml

uvは、PEP 621に準拠したpyproject.tomlファイルを使ってプロジェクトのメタデータや依存関係を管理します。uv initで生成されるpyproject.tomlに、プロジェクト名やバージョン、説明などを記述できます。 また、uv addで追加した依存関係もここに追記されます。

# pyproject.toml の例
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome Python project"
dependencies = [
    "requests",
]

[project.optional-dependencies]
dev = [
    "pytest",
    "ruff",
]

このファイルは、プロジェクトの基本的な構成を定義する中心的な役割を果たします。

2. Pythonバージョン指定 .python-version

uv python useコマンドを実行すると、カレントディレクトリに.python-versionファイルが生成されます。 このファイルには、プロジェクトで使用するPythonのバージョン番号（例: 3.11.8）が一行で記述されます。uvは、このファイルを参照して、自動的に適切なPython環境を使用します。

# .python-version の内容例
3.11.8

Gitリポジトリにこのファイルを含めることで、チームメンバー全員が同じPythonバージョンを使用するよう強制できます。

3. キャッシュディレクトリの変更

uvは、ダウンロードしたパッケージなどをグローバルキャッシュに保存し、再利用することで高速化を図っています。 このキャッシュディレクトリの場所は、環境変数UV_CACHE_DIRで変更できます。 デフォルトでは、OSごとの標準的なキャッシュパスが使用されます。

例えば、キャッシュを特定のディレクトリに集約したい場合です。

# .bashrc や .zshrc などに追加
export UV_CACHE_DIR="/path/to/my/uv_cache"

これにより、ディスク容量の管理や、特定の環境でのキャッシュ共有が容易になります。

4. コマンドエイリアスの設定

uvのpip互換インターフェースを活用するために、シェルのエイリアスを設定することが推奨されます。 これにより、普段使いのpipコマンドをuvに置き換え、高速化の恩恵を常に受けられます。

例えば、pipコマンドをuv pipにエイリアスする場合です。

# .bashrc や .zshrc などに追加
alias pip="uv pip"

この設定により、pip installと入力するだけで、内部的にはuv pip installが実行されるようになります。 既存のワークフローを大きく変えることなく、uvの高速性を活用できるでしょう。

今日からできる実行プラン — 3ステップで始める

uvの導入は非常に簡単です。 今日からでもすぐに始められます。 以下の3ステップで、あなたのPython開発を加速させましょう。

ステップ1: uvをインストールする

まずは、あなたのOSに合った方法でuvをインストールします。 公式推奨のスタンドアロンインストーラを使うのが最も手軽です。

# macOS / Linux の場合
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を実行して、正しくインストールされたか確認しましょう。

uv --version

ステップ2: 新規プロジェクトでuv initを試す

次に、新しいPythonプロジェクトをuvで管理してみましょう。 簡単なテストプロジェクトを作成し、uv initから始めてみてください。

mkdir my-new-uv-project
cd my-new-uv-project
uv init
uv add fastapi uvicorn  # 例としてFastAPIとUvicornを追加

これにより、高速な仮想環境の作成とパッケージのインストールを体験できます。uv run uvicorn main:appのようなコマンドで、アプリケーションの起動も試してみてください。

ステップ3: 既存プロジェクトでuv pip installを試す

最後に、既存のPythonプロジェクトにuvを適用してみましょう。 特にrequirements.txtを使用しているプロジェクトであれば、uv pip install -r requirements.txtの速度を実感できるはずです。

# 既存のプロジェクトディレクトリに移動
cd /path/to/your/existing/project

# requirements.txt がある場合、uvを使ってインストール
uv pip install -r requirements.txt

このコマンド一つで、あなたの開発環境のセットアップ時間が劇的に短縮されることでしょう。 ぜひ、uvをあなたのPython開発に導入し、その圧倒的なパフォーマンスを体験してください。

参考文献

• uv GitHubリポジトリ
• uv 公式ドキュメント
• Using uv: A Modern Python Workflow