⚡

今年を振り返る:pipから「uv」に乗り換えた話

に公開

2025年ももう終わりに近づいていますね。
今年一番の変化といえば、やはりコーディングエージェントの爆発的な進歩ではないでしょうか。

Claude Codeにコードを書かせては、スクラップ&ビルドを繰り返す日々。
何度も繰り返すパッケージ管理が面倒くさいことに今更きづいたといいますか・・・

「uvってのが速くてイイらしい」というのは知っていたんです。
でも、「とりあえずpipで間に合ってるからいいや」と後回しにしてきました。

しかし、AIに任せるコード量が増えるにつれ、「あれ、このコード動くけど依存関係どうなってるの?」「環境汚してない?」 という不安。
トレーサビリティや再現性がないのは問題だよなぁっと。

そこで uv に移行してみたんですが、これがAIコーディングにマッチするツールでした。
pip + venv で開発を行ってきた人が、迷わず uv に移行するためのガイドとしてまとめました。


【脱pip】「uv」移行ガイド

1. なぜ uv に変えるべきなのか?

単刀直入に言うと、「速い」上に「全部入り」だからです。

これまでPythonの開発環境構築には、複数のツールを使い分ける必要がありました。

  • パッケージ管理: pip
  • 仮想環境管理: venv / virtualenv
  • Pythonバージョン管理: pyenv
  • 依存関係ロック: pip-tools / poetry / pip freeze

uv はこれらをたった1つのバイナリで解決します。
Rust製のため動作が驚異的に高速です。pip install で待たされていた時間が、一瞬で終わるようになります。

2. インストール方法

Mac / Linux / Windows (WSL含む) で以下のコマンドを実行するだけです。

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 install uv でも入りますが、uv 自身のアップデート管理やPython環境自体の管理を行うために、上記のようなスタンドアロンインストールが推奨されます。


3. 基本コマンド:pip との対比表

まず、これまで pip でやっていた操作が uv でどうなるかを比較してみましょう。

目的 これまでのコマンド (pip/venv) uv のコマンド
仮想環境の作成 python -m venv .venv uv venv (※通常は自動管理されるので不要)
パッケージのインストール pip install requests uv add requests
開発用パッケージの追加 pip install pytest (管理は手動) uv add --dev pytest
依存関係の保存 pip freeze > requirements.txt 自動 (pyproject.toml と uv.lock に保存)
環境の再現(インストール) pip install -r requirements.txt uv sync
スクリプトの実行 source .venv/bin/activate && python app.py uv run app.py
Python自体のインストール pyenv install 3.12 uv python install 3.12

4. 実際のワークフロー:ゼロからプロジェクトを作る場合

ここからは、実際に uv を使った開発の流れを解説します。

ステップ1: プロジェクトの初期化

これまではフォルダを作って venv を作って…としていましたが、uv では以下のコマンド一発です。

mkdir my-project
cd my-project
uv init

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

  • .gitignore: gitの管理対象外のファイル・フォルダを指定
  • .git: Gitリポジトリ本体
  • pyproject.toml: 現代的な設定ファイル(requirements.txt の代わり)
  • .python-version: 使用するPythonバージョン
  • main.py: サンプルスクリプト
  • README.md: プロジェクトのREADMEファイル

これでプロジェクトの雛形が生成されます。

ステップ2: ライブラリの追加

例えば pandas を入れたい場合:

uv add pandas

ここがポイント:

  1. このコマンドを打った瞬間、仮想環境(.venv)がなければ勝手に作ってくれます。
  2. pandas を超高速でインストールします。
  3. pyproject.toml に依存関係を書き込みます。
  4. uv.lock というファイルを作成し、バージョンの固定(ロック)を行います。

これでもう、「pip install したけど requirements.txt に書き忘れた」という失態は起きません。

ステップ3: スクリプトの実行

ここが pip ユーザーにとって一番のパラダイムシフトです。
「仮想環境をactivateする」という操作はもう不要です。

uv run main.py

uv run コマンドを使うと、自動的にプロジェクトの仮想環境(.venv)を使ってスクリプトを実行してくれます。もし依存関係が同期されていない場合は、実行前に自動で修正してくれます。

(補足)一時的な実行とキャッシュ

プロジェクトを作らずに単発でスクリプトを動かす場合も、uv は一時的な仮想環境を作成して実行します。これらはキャッシュされるので2回目以降は高速です。
キャッシュが溜まってきたら、以下のコマンドで掃除できます。

  • uv cache prune: 古いキャッシュだけ削除
  • uv cache clean: 全消去

キャッシュされている場所を知りたい場合はuv cache dirで確認できます

uv cache dir
> C:\Users\username\AppData\Local\uv\cache

5. 既存のプロジェクト(requirements.txt)からの移行

「今あるプロジェクトを uv に移行したい」という場合はどうすればいいか?

手順

  1. プロジェクトフォルダに移動します。

  2. uv で初期化します。

    uv init
    
  3. 既存の requirements.txt を読み込みます。

    uv add -r requirements.txt
    

    (開発用ライブラリが分かれているなら uv add --dev -r requirements-dev.txt)

  4. これで pyproject.toml と uv.lock が生成されました。

  5. もう requirements.txt は削除してOKです!


6. さらに便利な機能:Pythonバージョンの管理

pyenv を使ったPythonのバージョンの管理はuvではどうするのか?

特定のバージョンでコマンドを実行したい場合:

# Python 3.12 で実行(インストールされてなければ勝手に入れてくれる!)
uv run --python 3.12 hello.py

プロジェクトのPythonバージョンを固定したい場合:

# プロジェクトをPython 3.11に固定
uv python pin 3.11

これで、チームメンバー全員が簡単に同じPythonバージョンを利用できます。

7. AIコーディングエージェントと相性抜群な理由

AIエージェントを使った開発こそ、uv を使うべきです。理由は主に3つあります。

① 「1ファイル完結」で動くコードを作ってもらえる (PEP 723)

AIに「Webスクレイピングのスクリプト書いて」と頼んだ時、これまでは「コードをコピペ」して「必要なライブラリを目視確認してpip install」という手順が必要でした。

uv は PEP 723 (Inline Script Metadata) をサポートしています。これにより、AIに対して**「必要なライブラリをスクリプトの冒頭に記述して」**と指示するだけで済みます。

AIに書いてもらうコードの例:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "pandas",
# ]
# ///

import requests
import pandas as pd
# ... 以下処理 ...

このファイルを保存して uv run script.py と叩くだけで、uv が一時的な仮想環境を作成し、ライブラリをインストールして実行してくれます。**「コピペして即実行」**が現実のものになります。

② AIによるコマンド操作のミスが減る

AIエージェントにターミナル操作を許可している場合、pip だと「仮想環境に入り忘れてグローバル環境を汚した」「OSごとにインストールコマンドが違う」といったミスが起こりがちです。

uv なら、AIに実行させるコマンドは常にシンプルです。

  • uv add <ライブラリ名>: インストールから記録まで完結。
  • uv run <ファイル名>: 環境の有効化を気にせず実行。

コマンドが統一されており、かつ「副作用」が自動処理されるため、AIが自律的にエラーを修正しやすくなります。

③ 試行錯誤のループが爆速になる

AI開発は「生成 → エラー → 修正」のサイクルの繰り返しです。
このサイクルの中で、パッケージの依存解決に毎回数十秒待たされると、思考のリズムが途切れてしまいます。uv の圧倒的なスピードは、このAIとの対話サイクルを止めないために非常に重要です。


8. ここがつまずくかも:移行時の注意点

移行時に「あれ?」となりがちなポイントをまとめました。

① IDE(VS Code / PyCharm)が環境を認識しない?

uv はコマンド一発で裏側で環境を作るため、IDEへの設定が必要な場合があります。

  • VS Code: コマンドパレット (Ctrl+Shift+P) → Python: Select Interpreter を開き、プロジェクト内の .venv を選択してください。
  • PyCharm: 設定から Interpreter の追加で「Existing environment」を選び、プロジェクト内の .venv/bin/python を指定します。

② pip install の手癖が抜けない

ついつい手癖で pip install numpy と打ってしまいがちです。
動きますが、pyproject.toml に記録されません。 そのため、後で uv sync した瞬間に消されてしまいます(これが一番のトラップです!)。
「インストールは必ず uv add」と念じましょう。

③ PyTorch などの「CPU版 / GPU版」の指定

uv ではコマンドライン引数ではなく、設定ファイルでソースを管理する思想です。
例えばCPU版のPyTorchを入れる場合:

uv add torch --index-url https://download.pytorch.org/whl/cpu

一度こうして実行すれば、設定ファイルに記録され、次回からは uv sync だけで正しいバージョンが入ります。

④ チームメンバーがまだ pip を使っている場合

自分だけ uv を使う場合、uv.lock をコミットしても他のメンバーは使えません。
その場合は export 機能を使います。

# uv.lock の内容を requirements.txt に書き出す
uv export --format requirements-txt > requirements.txt

これをコミットフックなどで自動化しておけば、自分は uv で快適に開発しつつ、チームには requirements.txt を提供できます。

⑤ AIエージェントはpipを使いがち

AIエージェントに任せていると、まだまだpipでインストールを行おうとするのでuvを使うように強制せておいたほうがよいです。

  • CLAUDE.md(Claude code)やプロジェクトルール(cursor)など、使用しているAIエージェントで指示を設定できるのでuvを使用するように指示を書いておきましょう。
  • 明示的に仮想環境を作っておく、uv venvで.venvを作成しておく。
  • requirements.txt とかpipを連想させるファイルは削除しておく
  • .bashrcをつかってpipの呼び出しを制限する。強引なやり方ですが、エリアスを設定してエラーメッセージを返して、AIにpipが使えない環境であることを理解させます。
    エラーメッセージにuv pip <command>が利用できるように書いておけばAIを誘導できます。この方法は他にも影響がでるので副作用が大きいです。
# pipの使用を禁止してuvを強制する
pip() {
    echo "------------------------------------------------------------"
    echo "ERROR: 'pip' is disabled in this project."
    echo "Please use 'uv' for package management."
    echo "  - To add a package:    uv add <package>"
    echo "  - To install deps:     uv sync"
    echo "  - To run with pip-sync: uv pip <command>"
    echo "------------------------------------------------------------"
    return 1
}
export -f pip

その他の注意点

  • uv.lockはサイズが大きいので読み込まないように指示する。コンテキストを消費してしまわないように.claudeignoreファイルにuv.lockを追加しておきましょう。(Claude codeの場合)

8. まとめ

uv に移行することで得られるメリットは以下の通りです。

  1. とにかく速い: 依存解決とインストールが爆速。
  2. 管理が楽: pyproject.toml による標準的な依存管理。
  3. ツールが減る: pip, venv, pyenv が uv ひとつに。
  4. 再現性が高い: ロックファイルで「私の環境では動くのに」問題が激減。

そして何より、AIコーディングエージェントとの相性が抜群です。
ぜひ年末年始の開発で試してみてください。

Discussion