docker-compose启动FastAPI报错uvicorn未在$PATH的解决方法

通过docker-compose部署FastAPI应用时，producer服务启动失败，抛出错误：

Cannot start service producer: OCI runtime create failed: container_linux.go:367: starting container process caused: exec: "uvicorn": executable file not found in $PATH: unknown

当前使用的Dockerfile配置：

FROM python:3.9-alpine
WORKDIR /code/producer
COPY requirements.txt requirements.txt
RUN pip install -r requirements.txt
COPY *.py /code/producer
CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "80"]

报错核心是容器内找不到uvicorn可执行文件，通常由三类问题导致：

• requirements.txt中未声明uvicorn依赖，执行pip安装步骤时根本没有安装uvicorn包
• Alpine镜像下pip安装可执行文件的路径未被纳入PATH，或者uvicorn因为缺少编译依赖安装失败，构建时未关注报错日志误以为安装成功
• 直接调用uvicorn命令的方式对环境路径依赖较强，一旦路径配置异常就会触发找不到命令的报错

• 先检查requirements.txt，确保已经写入必要依赖，示例如下：

fastapi>=0.100.0
uvicorn[standard]>=0.23.2

如果构建时出现依赖编译报错，可以在Dockerfile的pip安装步骤前，补充Alpine编译依赖安装命令：RUN apk add --no-cache gcc musl-dev libffi-dev

• 替换原有Dockerfile配置，改用更稳定的模块调用方式启动uvicorn，规避PATH路径问题：

FROM python:3.9-alpine
WORKDIR /code/producer
# 升级pip避免旧版本安装依赖异常
RUN pip install --no-cache-dir --upgrade pip
COPY requirements.txt .
# 安装依赖，禁用缓存减小镜像体积
RUN pip install --no-cache-dir -r requirements.txt
COPY *.py .
# 通过python模块方式调用uvicorn，不依赖系统PATH中的可执行文件
CMD ["python", "-m", "uvicorn", "api:app", "--host", "0.0.0.0", "--port", "80"]

• 清除旧镜像缓存重新构建，再启动服务：

docker-compose build --no-cache producer
docker-compose up -d producer

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