Docker部署FastAPI应用报错：fastapi可执行文件不在$PATH中

Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "fastapi": executable file not found in $PATH: unknown

尝试将FastAPI应用容器化时出现上述报错，已试过用uvicorn替代fastapi-cli、取消构建器模式，问题依旧。

Dockerfile #

FROM python:3.12 as builder

# install and setup poetry config
RUN pip install poetry==1.8.2

ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_IN_PROJECT=1 \
    POETRY_VIRTUALENVS_CREATE=1 \
    POETRY_CACHE_DIR=/tmp/poetry_cache

WORKDIR /navigation

COPY pyproject.toml poetry.lock ./
# poetry complains if there is no README file
RUN touch README.md

# install without dev dependencies + remove poetry cache
RUN poetry install --without dev && rm -rf $POETRY_CACHE_DIR

FROM python:3.12-alpine as runtime

ENV VIRTUAL_ENV=/navigation/.venv \
    PATH="/navigation/.venv/bin:$PATH"

COPY --from=builder ${VIRTUAL_ENV} ${VIRTUAL_ENV}

COPY navigation ./navigation

CMD ["fastapi", "run", "main.py", "--proxy-headers", "--port", "80"]

docker-compose.yml #

services:
  navigation-api:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./navigation:/navigation

pyproject.toml #

[tool.poetry.dependencies]
python = ">=3.12,<3.13"
fastapi = "^0.111.0"
prisma = "^0.13.1"

问题根源 #

核心问题是本地挂载目录覆盖了容器内的虚拟环境路径，同时可执行文件的路径识别存在偏差：

• docker-compose里的./navigation:/navigation会把本地目录直接覆盖容器内的/navigation，而虚拟环境.venv就在该目录下，挂载后容器内的虚拟环境被替换，自然找不到fastapi/uvicorn；
• 代码复制路径与CMD命令里的文件路径不匹配，进一步加剧了执行问题。

修复方案 #

1. 调整挂载路径，避免覆盖虚拟环境

修改docker-compose.yml，只挂载代码目录，不覆盖容器内的/navigation根目录：

services:
  navigation-api:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./navigation:/navigation/navigation  # 仅挂载业务代码目录
    ports:
      - "80:80"  # 可选，方便本地访问容器服务

2. 修正CMD命令的文件路径与可执行文件位置

直接指定虚拟环境内可执行文件的绝对路径，同时修正main.py的实际路径：

CMD ["/navigation/.venv/bin/fastapi", "run", "navigation/main.py", "--proxy-headers", "--port", "80"]

3. 验证虚拟环境复制完整性（可选）

在builder阶段添加验证步骤，确认可执行文件存在：

# 在poetry install后添加
RUN ls -la /navigation/.venv/bin/

4. 简化单阶段构建（可选）

如果不需要多阶段构建的优化，可以直接用单阶段安装，避免虚拟环境路径问题：

FROM python:3.12-alpine

WORKDIR /navigation

RUN pip install poetry==1.8.2

ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_CREATE=false  # 直接安装到系统Python环境

COPY pyproject.toml poetry.lock ./
RUN touch README.md
RUN poetry install --without dev

COPY navigation ./navigation

CMD ["fastapi", "run", "navigation/main.py", "--proxy-headers", "--port", "80"]

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