Docker构建FastAPI项目报错：uv命令未找到

问题根源 #

你把uv复制到了/Scripts/目录，但这个目录不在Linux容器的PATH环境变量中，系统无法找到uv命令；同时你误用了Windows的路径习惯（Scripts），Linux容器里虚拟环境的可执行文件目录是bin而非Scripts。

修复方案 #

方案1：将uv复制到系统默认PATH目录（推荐） #

修改Dockerfile中安装uv的行，把uv和uvx复制到Linux系统默认包含在PATH里的/usr/local/bin目录：

FROM python:3.11

# Install uv.
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/

# Copy the application into the container.
COPY . /app

# Install the application dependencies.
WORKDIR /app
RUN uv sync --frozen --no-cache

# Run the application.
CMD ["/app/.venv/bin/uvicorn", "src.main:app", "--port", "80", "--host", "0.0.0.0"]

方案2：将/Scripts/添加到PATH环境变量 #

如果坚持使用/Scripts/目录，需要手动将其加入PATH：

FROM python:3.11

# Install uv and add to PATH.
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /Scripts/
ENV PATH="/Scripts:${PATH}"

# Copy the application into the container.
COPY . /app

# Install the application dependencies.
WORKDIR /app
RUN uv sync --frozen --no-cache

# Run the application.
CMD ["/app/.venv/bin/uvicorn", "src.main:app", "--port", "80", "--host", "0.0.0.0"]

关键注意点 #

• Linux容器中，虚拟环境的可执行文件存放在.venv/bin/而非Windows的.venv/Scripts/，所以启动命令里的路径必须修改，否则后续运行也会报错。
• 可在构建时添加RUN ls /app/.venv命令，验证虚拟环境的目录结构是否正确。

内容的提问来源于stack exchange，提问作者GEBRU