uvって結局どこまでやる道具なのか：uv add と uv run から見えてくる全体像

uv は、パッケージ導入や仮想環境の作成だけでなく、Python 本体の導入、プロジェクトの初期化、依存関係とロックファイルの管理、コマンド実行、ツールの導入まで扱えます。

そのため、最初は「pip は入れる、venv は分ける、uv はまとめる」で理解してよいのですが、uv を使い続けるなら、それだけでは少し狭くなります。

uv pip install は、pip に近い感覚で使える入口です。既存の pip 手順を読み替えたいときや、まずは動かしてみたいときに自然です。

一方の uv add は、uv のプロジェクト運用に寄った入口です。依存関係をその場で入れて終わりにするのではなく、プロジェクトの情報として持ち、後の uv lock や uv run につながっていきます。

ここはかなり大事な前提です。uv add は、「いまいるフォルダに適当にパッケージを入れる」ためのコマンドというより、そのディレクトリを uv のプロジェクトとして扱う前提で使うコマンドです。

つまり、uv add を自然に使うには、少なくとも pyproject.toml があること、そして通常は uv init 済みであることを前提に考えると分かりやすいです。

最初の基本手順

新しくプロジェクトを始めるなら、まずは対象ディレクトリで uv init を実行します。

これで、uv がプロジェクトとして扱うための基本ファイルが作られます。とくに重要なのが pyproject.toml です。以後、依存関係やプロジェクトの情報は、このファイルを中心に管理していくことになります。

そのうえで、必要なライブラリをプロジェクト依存関係として追加するなら、次に使うのが uv add です。

ここでやっているのは、単にその場の環境へ入れることだけではありません。このプロジェクトは requests に依存しているという情報を、プロジェクト側に持たせる動きです。だから uv add は、uv pip install よりも「プロジェクト運用」の色が濃いわけです。

さらに、実際にコードを動かすときは uv run が自然につながります。

この流れをひとつのまとまりで見ると、次のようになります。

uv init
uv add requests
uv run python main.py

それぞれ何をしているのか

uv init は、これから管理するプロジェクトの土台を作るコマンドです。pyproject.toml がない状態でいきなり uv add を見るより、先にこの段階を意識した方がずっと理解しやすくなります。

uv add requests は、そのプロジェクトに必要な依存関係を追加するコマンドです。単に「今の環境に requests を入れる」より、「このプロジェクトは requests を使う」と宣言する意味合いが強くなります。

uv run python main.py は、そのプロジェクトの文脈で Python を実行するための入口です。環境や依存関係をプロジェクト側で見ながら実行できるので、uv の流れとして自然です。

uv を最初に見ると、uv venv と uv pip install が目立つので、「venv と pip をまとめたもの」と理解しやすいです。これは悪い理解ではありません。

ただ、そこから少し先へ進むと uv init、uv add、uv lock、uv run、uv python install、uv tool install まで現れます。ここまで来ると、uv はもう環境作成とパッケージ導入だけの道具ではありません。

つまり、入口は「pip + venv をまとめる」でよくても、実態としては Python 開発まわりの周辺作業をかなり広く統合している と見た方が自然です。

1. Python 本体の管理

uv は、仮想環境の中だけで完結する道具ではありません。たとえば uv python install 3.12 のように、使いたい版の Python 本体を入れるところまで扱えます。

2. 仮想環境の作成

ここは入口として見えやすい部分です。uv venv で仮想環境を作り、その中で作業できます。

3. パッケージ導入

パッケージ導入には、さきほど見た二つの入口があります。pip 互換寄りに入るなら uv pip install、プロジェクト運用寄りに入るなら uv add です。

4. プロジェクト管理

uv は、プロジェクトを作り、依存関係を加え、ロックし、実行する流れまで持っています。つまり「環境を作って終わり」ではなく、「そのプロジェクトをどう育てるか」まで守備範囲に入っています。

uv init
uv add requests
uv run python main.py

5. ツール導入

さらに uv は、開発ツールを入れて使う入口も持っています。ここまで来ると、uv は Python エコシステム全体の周辺作業をまとめる現代的な統合ツールだと見るのが自然です。

uv pip install が自然な場面

pip の感覚でまず触りたいとき、既存の pip 手順を読み替えたいとき、学習用に小さく試したいときは uv pip install が分かりやすいです。コマンドの意味が直感的で、入口としてやさしいからです。

uv add が自然な場面

これから uv の流れでプロジェクトを育てるなら、uv add の方が本流に近いです。依存関係をプロジェクトの情報として持ち、uv lock や uv run とつながるからです。

この違いは、「今の環境に入れる」という見方で止まるか、「このプロジェクトの依存関係として持つ」という見方に進むか、と言い換えてもよいでしょう。

Windows で仮想環境を有効化するとき、PowerShell では次のようなコマンドを使います。

ただし、この Activate.ps1 がそのまま動かず止まることがあります。原因の一つとして、PowerShell の実行ポリシーが関係することがあります。

ここで大事なのは、「自分だけがおかしいわけではない」と知っておくことです。これは Windows 特有の詰まりどころで、かなりよくある部類です。

この場では深掘りしませんが、少なくとも PowerShell と実行ポリシーが関係することがある と知っているだけで、不安はかなり減ります。

最初は、uv venv で環境を作り、必要なら有効化して、uv pip install でライブラリを入れる。この流れで十分です。

uv venv
uv pip install requests

ただ、少し慣れてきたら、uv add や uv run の考え方も早めに知っておくと楽になります。単に入れるだけでなく、プロジェクトとして管理する視点に自然につながるからです。

uv は、最初は pip や venv をまとめて扱いやすくした道具として理解できます。ただ、実際には Python 本体、プロジェクト、実行、ツールまでかなり広く扱います。

そして uv pip install と uv add は、どちらが正しいかではなく文脈の違いです。前者は pip 互換寄りの入口、後者はプロジェクト運用寄りの入口。この二つが見分けられるようになると、uv の全体像はかなりつかみやすくなります。