👌

uv で .venv を使わず devcontainer を構築したときのエラーと対処法

に公開
Docker
pyhton
dev container
uv
tech

エラー内容

devcontainer 環境で .venv を作成せずに uv を実行したところ、以下のエラーが発生しました：

Project virtual environment directory '/usr/local/' cannot be used because it is not a valid Python environment (no Python executable was found)

前提条件

uv で仮想環境（.venv）を作成せずに実行するには、UV_PROJECT_ENVIRONMENT 環境変数で明示的に Python 実行環境のパスを指定する必要があります。

📚 参考ドキュメント：Project Environment Path

今回使用した devcontainer の設定は以下の通りです。

Dockerfile 

FROM mcr.microsoft.com/vscode/devcontainers/base:bullseye

ARG USERNAME=vscode

COPY --from=ghcr.io/astral-sh/uv:0.6.14 /uv /uvx /bin/

devcontainer.json 

{
  "name": "python-pj",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "features": {
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.13"
    }
  }
}

この構成の特徴として、Python をベースイメージに含めず、features によってインストールしている点が挙げられます。

結論

UV_PROJECT_ENVIRONMENT に以下のパスを指定することで解消されます：

export UV_PROJECT_ENVIRONMENT=/usr/local/python/current/

反映したDockerfileの例

FROM mcr.microsoft.com/vscode/devcontainers/base:bullseye

ARG USERNAME=vscode

COPY --from=ghcr.io/astral-sh/uv:0.6.14 /uv /uvx /bin/
ENV UV_PROJECT_ENVIRONMENT=/usr/local/python/current/

詳細な解説

Python が同梱されたベースイメージ（例：python:<version>）を使っていれば、このエラーは発生しません。

uv は UV_PROJECT_ENVIRONMENT に指定されたパスを、Python バイナリのルートディレクトリとして認識します。

  • Python 同梱イメージでは /usr/local/ に Python バイナリがあるため、/usr/local/ を指定しても問題は起きません。
  • 一方、features によって Python を追加インストールしている場合、Python バイナリは /usr/local/python/current/bin/python に配置されます。

このため /usr/local/ を指定すると uv はそこに有効な Python 実行ファイルがないと判断し、上記のエラーになります。

✅ 正しいパスは /usr/local/python/current/ です。

Discussion