uv pip install が「No virtual environment found」でインストールできない

要約

pip の代わりに uv を使おうとして uv pip install を実行すると、何もインストールされずに止まる（終了コード 2）。

error: No virtual environment found; run `uv venv` to create an environment, or pass `--system` to install into a non-virtual environment

公式ドキュメント（新しいタブで開く）↗にあるとおり、uv は pip と違って既定で仮想環境を使うことを求める。uv pip install が入れる先として探すのは、VIRTUAL_ENV（有効化した仮想環境）、CONDA_PREFIX（有効化した Conda 環境）、カレントディレクトリか最も近い親ディレクトリの .venv の順で、どれも無ければこのエラーになる。
上の表示は uv 0.13.0・Python 3.12 で、空のディレクトリで uv pip install requests を実行したものだ。

解決策

1. uv venv で .venv を作る

uv venv
uv pip install requests

有効化しなくても、uv はカレントか親ディレクトリの .venv に入れる。
サブディレクトリで実行しても Using Python 3.12.14 environment at: /w/a/.venv のように親の .venv が使われた。

2. 使うときは uv run か .venv の python で

.venv に入れた直後に素の python -c "import requests" を実行すると ModuleNotFoundError になった。.venv の python を使えば読み込める。

uv run python -c "import requests"
# または有効化してから使う
source .venv/bin/activate        # Windows は .venv\Scripts\activate
python -c "import requests"

3. Docker や CI では --system

使い捨てのコンテナや CI のように、システムの Python に直接入れてよい環境に限って --system を付ける。

uv pip install --system requests

OS が管理する Python に入れると、OS 側のパッケージと衝突することがある。
手元の開発環境では 1 の方法を使う。

4. 別の場所の環境を使う

.venv 以外の仮想環境なら、有効化して VIRTUAL_ENV を設定するか、--python でその環境を指定する。

よくある原因

1. .venv をまだ作っていない: 新しいディレクトリで最初に uv pip install を打っている。
2. システムの Python に入れるつもりでいる: pip ならそのまま入る場面でも、uv は --system を付けない限り仮想環境でない Python を無視する。
3. 環境が探す場所の外にある: .venv 以外の名前や別のディレクトリに仮想環境を作り、有効化もしていない。
4. 入れた後に素の python で動かしている: エラーは消えても、.venv に入ったパッケージは素の python からは見えない。