Django项目Docker中启动Celery报ModuleNotFoundError错误

两次报错本质是同一个问题：容器内Python的模块搜索路径（sys.path）没有包含项目代码所在目录，不管怎么调整-A参数、指定工作目录都没用，Python根本扫不到对应的包：

• 传config时，容器当前工作目录不在搜索路径里，找不到config包
• 传myproj.config时，myproj文件夹的父目录不在搜索路径里，找不到myproj包

按优先级选对应操作即可：

方案1：补PYTHONPATH环境变量（最快生效，无需改代码/镜像结构） #

直接修改docker-compose.yml里的worker配置，把项目父目录加入Python搜索路径即可。假设你Dockerfile中把项目代码拷贝到了容器内的/app路径（即容器内项目路径为/app/myproj/），配置修改如下：

worker:
    build:
      context: "."
      target: "app"
    command: celery -A myproj.config worker -l info
    entrypoint: []
    environment:
      # 这里填myproj文件夹所在的父目录，不要填到myproj本身
      - PYTHONPATH=/app
    # 对齐工作目录到项目父目录，不要进入myproj文件夹内部
    working_dir: /app

注意：/app要和你Dockerfile里COPY指令的目标路径保持一致，比如Dockerfile里写的是COPY . /code/，这里PYTHONPATH就填/code。

方案2：安装项目为可编辑包（最规范，长期稳定） #

不想靠环境变量临时凑路径的话，直接调整镜像构建逻辑：

• 在项目根目录（和myproj文件夹同级）新建最小化的pyproject.toml，内容如下：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "myproj"
version = "0.1.0"
packages = ["myproj"]

• 在Dockerfile的构建步骤中加一行pip install -e .，同时把WORKDIR设为项目根目录（即myproj的父目录）。

配置完成后，不管在容器哪个路径启动celery，Python都能正常识别myproj包，直接用celery -A myproj.config worker -l info启动即可，不会再报模块找不到的错误。

• 不要把容器工作目录设到myproj文件夹内部，否则Python会把myproj下的内容识别为顶层包，既找不到外层的myproj包，也容易出现相对导入错误
• 检查config/__init__.py里的celery导入写法是否正确，参考写法：

from .celery import app as celery_app
__all__ = ("celery_app",)

不要写错相对导入路径，否则就算找到模块也会触发导入异常。

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