今さら聞けない uv add と uv pip install の違い

uv add requests と uv pip install requests。
どちらもパッケージをインストールするコマンドなので、使い分けに迷います。
インストール後に同じように import requests が通るなら、なおさらです。

違いは、プロジェクトに必要な依存として記録するか、対象のPython環境にインストールするかにあります。
この違いは、環境を同期したり、別の環境でプロジェクトを動かしたりするときに表れます。

二つのコマンドが変更するもの

uvで管理するプロジェクトでは、次の三つを区別すると整理しやすくなります。

対象	役割
pyproject.toml	プロジェクトに必要なパッケージと、許容するバージョン範囲などを宣言する
uv.lock	依存関係を解決した結果として、間接的に必要なパッケージも含めたバージョンなどを記録する
.venv	Pythonやインストール済みパッケージが置かれる、実行用の仮想環境

通常のプロジェクトで、オプションを付けずに依存を追加した場合の動作は次のとおりです。

操作	uv add requests	uv pip install requests
pyproject.toml の依存宣言を更新	する	しない
uv.lock を更新	する	しない
パッケージをインストール	する	する

uv add は依存の宣言からロックファイルの更新、プロジェクト環境への反映までを行います。
一方、uv pip install は対象環境にパッケージをインストールしますが、その操作をプロジェクトの依存宣言には反映しません。
両者の役割は、公式の uv add と パッケージのインストール に記載されています。

uv add --no-sync を使うと、依存宣言とロックファイルを更新し、環境への反映を省略できます。
また、uv add --script はスクリプト内の依存情報を扱います。
上の表は、こうしたオプションを使わないプロジェクト操作の比較です。

インストールできても依存として記録されたとは限らない

この違いを、小さなプロジェクトで確かめます。
検証環境はLinux、uv 0.11.17、CPython 3.14.5です。
別の仮想環境やConda環境を有効化していない状態で、プロジェクト環境の保存先などは既定の設定を使います。

まず、実験用のディレクトリを作り、uv add で idna を追加します。
後から入れる sniffio と区別できるよう、互いを依存として必要としない二つのパッケージを使います。

mkdir uv-command-demo
cd uv-command-demo
uv init --bare --no-workspace --vcs none --python 3.14
uv add idna

pyproject.toml の dependencies に idna が追加され、uv.lock と .venv も作成されます。
この時点で、idna はプロジェクトの依存として記録され、環境にも入っています。

続いて、uv pip install で sniffio を入れます。

uv pip install sniffio
uv run python -c "import sniffio; print('sniffio available')"

sniffio available

sniffio は使えます。
しかし、pyproject.toml と uv.lock の内容は、このインストールの前後で変わりません。
uv run で実行できたことも、依存として記録された証拠にはなりません。

次に、プロジェクト環境を明示的に同期します。

uv sync
uv run python -c "import sniffio"

uv sync によって sniffio が削除され、続くコマンドは次のエラーで終了します。

ModuleNotFoundError: No module named 'sniffio'

これは、sniffio がプロジェクトの依存として記録されていなかったためです。
最初から uv add sniffio で追加していれば、同期後も利用できます。
すでに uv pip install で入れてしまった場合も、uv add sniffio で依存に追加できます。

uv run と uv sync では、余分なパッケージの扱いが異なります。
既定の uv run は余分なパッケージを残しますが、既定の uv sync は削除します。
そのため、手元で uv run が成功していても、未登録のパッケージに依存している可能性があります。
この動作の違いは、公式の 同期時の余分なパッケージの扱い でも説明されています。

用途に合わせた使い分け

uvで管理するプロジェクトに依存を追加する

アプリケーションに必要なライブラリなら、uv add を使います。
テストなどの開発用の依存も、--dev を付けて記録できます。

uv add requests
uv add --dev pytest

pyproject.toml と uv.lock をGitで共有すれば、別の開発者も uv sync で依存をインストールできます。
環境へ入れる操作と、プロジェクトに必要な依存を記録する操作が一緒になるため、登録漏れを防ぎやすくなります。
依存の追加先については、公式の 依存関係の管理 を参照してください。

既存のrequirements.txtを使う

すでに requirements.txt で依存を管理していて、その運用を続ける場合は、uv pip install が使えます。
仮想環境がなければ、先に uv venv で作成します。

uv venv
uv pip install -r requirements.txt

この場合、依存の記録は requirements.txt 側で管理します。
uv pip install は、そのファイルを読み込んでインストールする役割です。
一時利用専用のコマンドではありません。

また、uv pip install を使うだけで「再現性がない」と決まるわけでもありません。
uv pip compile で間接依存までバージョンを固定した requirements.txt を作る運用もあります。
余分なパッケージも削除して、そのファイルに環境を合わせたい場合は uv pip sync を使います。
詳しい手順は公式の 環境のロック にあります。

requirements.txtからuvのプロジェクト管理へ移行する

今後は pyproject.toml と uv.lock で管理したい場合、初期化済みのuvプロジェクトで次のコマンドを使います。

uv add -r requirements.txt

同じ -r requirements.txt でも、uv add はその内容をプロジェクトの依存に取り込みます。
単に環境へインストールする uv pip install -r requirements.txt とは、目的が異なります。

ただし、間接依存まで固定したファイルをそのまま取り込むと、それらも直接の依存として追加されます。
移行時には、プロジェクトが直接必要とする依存を確認した方が、後の管理がしやすくなります。
複数の依存ファイルや制約を扱う場合は、公式の pipからuvプロジェクトへの移行ガイド が参考になります。

PyTorchのように取得先の設定が必要な場合

PyTorchでは、uv pip install を単純に uv add に置き換えるだけでは、希望する構成にならない場合があります。
CPU版やCUDA版などで配布物が分かれ、その多くが専用のパッケージインデックス（配布元）で提供されているためです。
例えば、LinuxでCPU版を指定して入れる手順には、次のような取得先の指定があります。uv公式のPyTorch導入ガイド

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

これを uv add torch だけに置き換えると、取得先を指定していないため、既定のPyPIから解決します。
インストールに成功しても、元のCPU版の指定を引き継いだことにはなりません。

uvのプロジェクト管理へ移行するなら、依存名に加えて取得先も記録します。
例えば、LinuxでCPU版の torch を使うプロジェクトでは、pyproject.toml に次の設定を追加してから uv add torch を実行できます。
すでに同じ設定項目がある場合は、そこへ統合します。

pyproject.toml

# 既存のプロジェクト設定に追加する部分
[tool.uv.sources]
torch = { index = "pytorch-cpu" }

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

explicit = true は、この配布元を明示的に指定したパッケージだけに使う設定です。
ほかの依存までPyTorchの配布元から取得することを避けられます。
CUDA版を使う場合やOSごとに取得先を変える場合も、必要な構成に合わせて設定します。uv公式のPyTorchインデックス設定

この設定例は、uv 0.11.17とCPython 3.14.5で uv add torch --no-sync による依存解決とロックファイルの生成まで確認しています。
PyTorch本体のインストールやGPUでの実行は検証していません。

また、uv pip install torch --torch-backend=auto のように実行環境に応じて取得先を選ぶ方法もありますが、--torch-backend は2026年9月26日の確認時点では uv pip 専用です。
このオプションをそのまま uv add に移すことはできません。uv公式のバックエンド自動選択

PyTorchも uv add で管理できますが、移行時にはCPU版やCUDA版の選択、対応するPythonやOSまで含めて確認する必要があります。
既存の環境構築手順を維持したい段階では、uv pip install を続ける選択もあります。
その場合は、取得先やバックエンドの指定も環境構築スクリプトなどに残します。

インストール先にも違いがある

二つのコマンドが、常に同じ環境にインストールするとは限りません。
通常の uv add は、プロジェクトの .venv を使います。
別の仮想環境を有効化していても、既定ではそちらに切り替わりません。
有効な環境を使うには --active を指定します。公式のプロジェクト環境の説明

一方、uv pip install は、環境の指定がなければ次の順番で探します。

1. VIRTUAL_ENV で示される、有効化された仮想環境
2. CONDA_PREFIX で示される、有効化されたConda環境
3. カレントディレクトリから親ディレクトリへ探して見つかる、最も近い .venv

仮想環境が見つからなければ、既定では uv venv での作成を求めます。
自動的にシステムのPythonへインストールするわけではありません。公式の環境の探索規則

「インストールしたはずなのにimportできない」ときは、依存宣言への記録に加えて、インストール先と実行先が一致しているかも確認する必要があります。

依存を追加するときは、まずプロジェクトがどのファイルで依存を管理しているかを確認すると選びやすくなります。
pyproject.toml と uv.lock で管理するプロジェクトなら uv add、既存の requirements.txt から環境に入れるなら uv pip install -r requirements.txt が出発点です。