この記事で分かること

Python環境管理の「何が問題だったのか」と uv が解決すること
uv のインストール方法（macOS / Linux / Windows）
uv だけでPythonバージョン管理・仮想環境・パッケージ管理を行う方法
実際のプロジェクトをゼロから作るハンズオン手順
既存の pip + venv プロジェクトから uv への移行方法
よくある落とし穴と対処法

はじめに

Pythonの開発環境を構築するとき、こんな経験はありませんか？

pyenv でPythonバージョンを管理して
python -m venv .venv で仮想環境を作って
pip install -r requirements.txt でパッケージをインストールして
気づけばツールが3つ、設定ファイルも3つ……

「環境構築だけで1時間消えた」——これはPython開発者の"あるある"です。

uv（ユーブイ） は、この問題を根本から解決するRust製のPythonパッケージマネージャです。Astral社（コードフォーマッター ruff の開発元）が開発しており、pip・venv・pyenv・pipx・poetry がやっていたことをたった1つのツールで、しかも爆速でこなします。

前提知識

用語	説明
パッケージマネージャ	ライブラリ（他人が作った便利なコード）をインストール・管理するツール。スマホの「アプリストア」のようなものです
仮想環境	プロジェクトごとにライブラリを分離する仕組み。料理でいえば「まな板を分ける」ことで食材が混ざらないようにするイメージです
`pyproject.toml`	Pythonプロジェクトの設定ファイル。プロジェクト名、依存ライブラリなどを記述します

uvが解決する「ツール乱立」問題

従来のPython開発では、やりたいことごとに別のツールが必要でした。

uvは「Pythonのnpm」とも呼ばれ、Node.jsの世界で npm や yarn が果たしている統合的な役割をPythonにもたらします。

インストール

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc  # または source ~/.zshrc

Windows（PowerShell）

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

インストール確認

uv --version
# uv 0.9.27 (例)

ハンズオン: プロジェクトをゼロから作る

ここからは実際に手を動かしていきます。「Web APIからデータを取得して表示する」 小さなプロジェクトを作りましょう。

Step 1: Pythonのインストール（pyenv不要）

uv はPython自体のインストールも管理できます。

# 利用可能なPythonバージョンを確認
uv python list

# Python 3.12をインストール
uv python install 3.12

Step 2: プロジェクトの初期化

# プロジェクトディレクトリを作成＆初期化
uv init my-api-client
cd my-api-client

これだけで以下のファイルが生成されます：

my-api-client/
├── .python-version    # 使用するPythonバージョン
├── pyproject.toml     # プロジェクト設定（pip の requirements.txt に相当）
├── README.md
├── hello.py           # サンプルスクリプト
└── .venv/             # 仮想環境（自動作成）

pyproject.toml の中身を見てみましょう：

[project]
name = "my-api-client"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

Step 3: パッケージの追加

# httpx（HTTPクライアント）を追加
uv add httpx

# 開発用の依存（テストツール）を追加
uv add --dev pytest

uv add を実行すると、以下が自動で行われます：

パッケージのダウンロードとインストール
pyproject.toml への依存追記
uv.lock（ロックファイル）の生成・更新

Step 4: コードを書いて実行

main.py を作成します：

import httpx

def main():
    """天気予報APIからデータを取得して表示する"""
    # Open-Meteo API（無料・APIキー不要）
    url = "https://api.open-meteo.com/v1/forecast"
    params = {
        "latitude": 35.6762,   # 東京
        "longitude": 139.6503,
        "current_weather": True,
    }

    response = httpx.get(url, params=params)
    weather = response.json()["current_weather"]

    print(f"東京の現在の天気:")
    print(f"  気温: {weather['temperature']}°C")
    print(f"  風速: {weather['windspeed']} km/h")

if __name__ == "__main__":
    main()

uv run でスクリプトを実行します：

uv run python main.py
# 東京の現在の天気:
#   気温: 15.2°C
#   風速: 12.3 km/h

ポイント: uv run は仮想環境のアクティベート（source .venv/bin/activate）を不要にします。uv が自動で仮想環境内のPythonを使ってくれます。

Step 5: テストの実行

uv run pytest tests/

速度の違いを体感する

uvの最大の特長は速度です。Rustで書かれた依存関係リゾルバにより、pipと比較して10〜100倍高速に動作します。

操作	pip	uv	速度差
依存関係の解決	数十秒〜数分	数秒	10〜100倍
パッケージのインストール（キャッシュあり）	数秒	ほぼ一瞬	50倍以上
ロックファイル生成	pip-compile で数十秒	数秒	10倍以上

体感としては、pip install でコーヒーを淹れに行っていた時間が、uv add では瞬きしている間に終わります。

既存プロジェクトからの移行

requirements.txt からの移行

# 既存プロジェクトに移動
cd existing-project

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

# requirements.txt の内容を一括追加
uv add $(cat requirements.txt)

pip 互換コマンド

いきなり全面移行するのが不安な場合、uv pip サブコマンドでpipと同じ感覚で使えます：

# pip install と同じ使い方
uv pip install requests

# pip freeze と同じ
uv pip freeze

# requirements.txt から一括インストール
uv pip install -r requirements.txt

CI/CDでの活用

GitHub Actionsでも公式のセットアップアクションが用意されています：

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v7
      - run: uv sync --locked --dev
      - run: uv run pytest

uv sync --locked は uv.lock の内容を完全に再現するコマンドです。「開発環境では動くのにCIでは動かない」問題を防ぎます。

よくある落とし穴と対処法

1. `uv` コマンドが見つからない

# PATHが通っていない場合
source ~/.bashrc  # または ~/.zshrc
# それでもダメなら
export PATH="$HOME/.local/bin:$PATH"

インストール直後のターミナルセッションでは、PATHが反映されていないことがあります。ターミナルを開き直すか、source でシェル設定を再読み込みしてください。

2. 既存の `.venv` と競合する

uvは既存の .venv を検出すると、そのPythonバージョンに合わせようとします。クリーンに始めたい場合は：

rm -rf .venv
uv venv --python 3.12

3. uv add と uv pip install の違いが分からない

コマンド	用途	pyproject.toml更新	uv.lock更新
`uv add パッケージ名`	プロジェクト管理（推奨）	する	する
`uv pip install パッケージ名`	pip互換モード	しない	しない

原則 uv add を使いましょう。uv pip install は移行期の一時的な手段と考えてください。

4. pyenv と共存できる？

できますが、uvだけで完結させるのがおすすめです。uv python install でPythonバージョン管理もできるため、pyenvは不要になります。共存させる場合は .python-version ファイルの管理主体を明確にしてください。

uvを使うべきとき・使わないほうがよいとき

判断基準	uvがおすすめ	従来ツール検討
新規プロジェクト	迷わずuv	—
個人開発〜小規模チーム	導入障壁が低い	—
CI/CDの高速化	大きな効果あり	—
大規模チーム（既存poetry運用）	—	段階的に移行を検討
conda 生態系（データサイエンス）	—	condaが適切な場合あり

まとめ

uvは「Pythonの環境構築がつらい」という長年の課題を、Rustの実行速度とモダンな設計で解決するツールです。

インストールは1行: curl -LsSf https://astral.sh/uv/install.sh | sh
覚えるコマンドは5つ: init, add, run, sync, python install
速度は体感10倍以上: Rustによる依存解決で待ち時間が激減
移行コストは低い: uv pip 互換モードで段階的に導入可能

「まだpipで消耗してるの？」とは言いませんが、一度uvの速度を体感すると、きっと戻れなくなるはずです。まずは小さなプロジェクトで試してみてください。

こちらもよく読まれています

Node.jsだけでTypeScriptを実行する時代が来た——ts-node・tsx不要の開発環境構築と移行ガイド