Docker Compose无法找到uvicorn模块的问题求助

常见排查点与修复方案 #

1. 确认Compose正确关联构建镜像 #

检查docker-compose.yml里的server服务是否指向了正确的构建目录，避免直接引用未安装依赖的外部镜像：

services:
  server:
    build: .  # 确保这里指向Dockerfile所在的根目录，不要随便替换成image: xxx（除非你已手动构建好镜像）
    # 其他配置（端口映射、环境变量等）

2. 避免Compose覆盖工作目录 #

如果Dockerfile里设置了WORKDIR /app，就别在Compose里用working_dir指定其他路径——否则Python会找不到安装在/app路径下的依赖包：

services:
  server:
    # 注释掉或删除这行：working_dir: /other/path

3. 统一启动命令的Python环境 #

确保Compose的command和Dockerfile里的启动逻辑一致，别混用系统Python和虚拟环境：

services:
  server:
    # 直接调用uvicorn命令（前提是Dockerfile里pip install时已将其加入PATH）
    command: uvicorn main:app --host 0.0.0.0 --port 8000
    # 如果用了虚拟环境，就写全路径：command: /app/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000

别直接用python3.8 -m uvicorn，除非你确认系统Python的site-packages里确实安装了uvicorn。

4. 强制重新构建镜像 #

Compose有时会复用旧缓存镜像，导致依赖没更新，执行以下命令强制刷新：

docker-compose build --no-cache
docker-compose up

5. 检查Dockerfile的依赖安装步骤 #

确保Dockerfile里正确执行了依赖安装，且顺序正确（先拷requirements.txt再安装，避免缓存失效）：

FROM python:3.8-slim

WORKDIR /app

# 先拷贝依赖文件，利用Docker缓存
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 再拷贝代码
COPY . .

# 统一启动命令
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

快速验证步骤 #

1. 先手动构建镜像：docker build -t my-fastapi .
2. 手动运行容器：docker run --rm my-fastapi，确认服务能正常启动
3. 修改Compose的server服务，直接用这个本地镜像：

services:
  server:
    image: my-fastapi
    ports:
      - "8000:8000"

如果这样能正常运行，说明之前Compose的构建环节存在问题，回到上面的排查点逐一验证。

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