今年を振り返る: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
ここがポイント:
- このコマンドを打った瞬間、仮想環境(
.venv)がなければ勝手に作ってくれます。 -
pandasを超高速でインストールします。 -
pyproject.tomlに依存関係を書き込みます。 -
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 に移行したい」という場合はどうすればいいか?
手順
-
プロジェクトフォルダに移動します。
-
uvで初期化します。uv init -
既存の
requirements.txtを読み込みます。uv add -r requirements.txt(開発用ライブラリが分かれているなら
uv add --dev -r requirements-dev.txt) -
これで
pyproject.tomlとuv.lockが生成されました。 -
もう
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 に移行することで得られるメリットは以下の通りです。
- とにかく速い: 依存解決とインストールが爆速。
-
管理が楽:
pyproject.tomlによる標準的な依存管理。 -
ツールが減る:
pip,venv,pyenvがuvひとつに。 - 再現性が高い: ロックファイルで「私の環境では動くのに」問題が激減。
そして何より、AIコーディングエージェントとの相性が抜群です。
ぜひ年末年始の開発で試してみてください。
Discussion