できない.dev

uv run「Failed to spawn」の原因と直し方

uv run の Failed to spawn は、打ったコマンドを uv add --dev pytest のように依存へ足せば直る。
環境に無いコマンドで出る。
os error 13 は実行権限の不足で、chmod +x で直る。

公開: 更新:

症状できない · exit 2
uv run pytest --version
Using CPython 3.12.16 interpreter at: /usr/local/bin/python3
Creating virtual environment at: .venv
error: Failed to spawn: pytest
  cause: No such file or directory (os error 2)
解決後できた · exit 0
uv run pytest --version
pytest 9.2.0

2026-11-14 に python:3.12(uv 0.13.8) で実際に打って取った出力。検証環境の詳細

要約

uv run pytest を打つと、uv 0.13.7 では次のエラーで止まることがある。
終了コードは 2 になる。

error: Failed to spawn: pytest
  cause: No such file or directory (os error 2)

Failed to spawn は、uv が渡されたコマンドを起動できなかったことを示す。
os error 2 はコマンドが見つからないときの形で、uv add --dev pytest のように依存へ足せば直る。
os error 13 は実行権限が無いときの形で、chmod +x で直る。

uv 0.12.0 では、同じエラーが次の文言で出る。

error: Failed to spawn: `pytest`
  Caused by: No such file or directory (os error 2)

実行例

python:3.12 と uv 0.13.8 では、uv run pytest が Failed to spawn と os error 2 で終了コード 2 になった。
uv add --dev pytest を実行すると通り、--no-dev 付きでは再び失敗した。
実行権限のないスクリプトは os error 13 で失敗し、chmod +x の後は通った。

$ uv --version
uv 0.13.8 (x86_64-unknown-linux-gnu)
$ uv run pytest --version
Using CPython 3.12.16 interpreter at: /usr/local/bin/python3
Creating virtual environment at: .venv
error: Failed to spawn: pytest
  cause: No such file or directory (os error 2)
$ echo $?
2
$ uv add --dev pytest
Resolved 13 packages in 337ms
Downloading pygments (1.2MiB)
 Downloaded pygments
Prepared 5 packages in 181ms
Installed 5 packages in 12ms
 + iniconfig==2.3.1
 + packaging==26.3
 + pluggy==1.7.0
 + pygments==2.21.0
 + pytest==9.2.0
$ uv run pytest --version
pytest 9.2.0
$ echo $?
0
$ uv sync --no-dev
Resolved 13 packages in 0.60ms
Uninstalled 5 packages in 6ms
 - iniconfig==2.3.1
 - packaging==26.3
 - pluggy==1.7.0
 - pygments==2.21.0
 - pytest==9.2.0
$ uv run --no-dev pytest --version
error: Failed to spawn: pytest
  cause: No such file or directory (os error 2)
$ echo $?
2
$ uv run pytest --version
Installed 5 packages in 9ms
pytest 9.2.0
$ echo $?
0
$ uv run s/hello.sh
error: Failed to spawn: s/hello.sh
  cause: Permission denied (os error 13)
$ echo $?
2
$ chmod +x s/hello.sh
$ uv run s/hello.sh
hello
$ echo $?
0

— 2026-11-14 時点の出力

検証環境Python 3.12.16 / Git 2.47.3 / uv 0.13.8 / 2026-11-14 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.16
  • Git 2.47.3
  • uv 0.13.8

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 依存に足す

uv add --dev pytest
uv run pytest --version

一度だけ使うなら、依存を変えずに起動できる。

uv run --with pytest pytest --version
uvx pytest --version

uvx はプロジェクトから分離した環境で動く(公式ドキュメント(新しいタブで開く))。
プロジェクト自体を読み込むテストには uv run を使う。

2. --no-dev を外す

uv run pytest --version を打つと、消えた開発用の依存が入り直して起動する。

3. 依存グループを指定する

uv run --group test pytest --version

毎回入れるなら、tool.uv.default-groups にグループを書く。

4. build-system を足す

[build-system]
requires = ["uv_build>=0.8,<1"]
build-backend = "uv_build"

src/app/__init__.py に main を置いた構成で、uv run hello が動くようになった。
[tool.uv] に package = true と書いても同じように動く。
新しく作るなら uv init --package app が [project.scripts] と [build-system] を書き出す。

5. 実行権限を付ける

chmod +x s/hello.sh
uv run s/hello.sh

よくある原因

  1. コマンドが依存に入っていない。
    pyproject.toml に pytest が無ければ、.venv/bin に pytest は作られない。
  2. uv sync --no-dev を実行すると、開発用の依存が .venv から消える。
    そのあとの uv run --no-dev pytest はこのエラーになる。
    uv run --no-dev だけでは入っている物は消えないので、開発用の依存が残っている環境では通る。
  3. [dependency-groups] のうち、既定で入るのは dev だけである。
    test というグループに入れた pytest は、指定しないと入らない。
  4. [project.scripts] に書いたコマンドは、build-system が無いと作られない。
    uv run のエラーに理由は出ない。
    uv sync を打つと Skipping installation of entry points の警告が出る。
  5. スクリプトに実行権限が無い。
    uv run s/hello.sh は Permission denied (os error 13) で止まる。
    打ち間違えたパスは os error 2 になる。
    .py のファイルは実行権限が無くても uv run t.py で動く。