1
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@76Hata(76Hata)

pip・venvはもう古い——Rust製パッケージマネージャ「uv」で爆速Python開発環境を構築するハンズオン入門

1
Posted at

この記事で分かること

  • 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 を実行すると、以下が自動で行われます：

  1. パッケージのダウンロードとインストール
  2. pyproject.toml への依存追記
  3. 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. インストールは1行: curl -LsSf https://astral.sh/uv/install.sh | sh
  2. 覚えるコマンドは5つ: init, add, run, sync, python install
  3. 速度は体感10倍以上: Rustによる依存解決で待ち時間が激減
  4. 移行コストは低い: uv pip 互換モードで段階的に導入可能

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

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

1
4
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?