Docker容器中Gunicorn启动Geodjango报ModuleNotFoundError错误排查

问题根因 #

该报错是Python模块搜索路径与容器内的项目目录结构不匹配导致：
你的Dockerfile中配置WORKDIR /app，并执行COPY . ./djangodocker，因此容器内实际的项目路径为：

• /app/djangodocker/manage.py
• /app/djangodocker/djangodocker/wsgi.py
  使用python manage.py runserver启动时，Django会自动将manage.py所在目录/app/djangodocker加入Python模块搜索路径，因此可以正常找到内层的djangodocker包；但Gunicorn启动时默认仅将当前工作目录/app加入搜索路径，无法匹配到内层的wsgi.py文件。

可用解决方案 #

方案1：直接修改Gunicorn启动命令 #

两种修改方式二选一即可：

1. 显式指定Python搜索路径

command: gunicorn --pythonpath /app/djangodocker djangodocker.wsgi:application --bind 0.0.0.0:8000

2. 先切换到项目根目录再启动

command: sh -c "cd /app/djangodocker && gunicorn djangodocker.wsgi:application --bind 0.0.0.0:8000"

方案2：优化Dockerfile配置，从根源避免路径问题 #

调整Dockerfile的工作目录设置，后续无需额外处理路径：

# GIS-OS as Layer
FROM gis-os as djangoproject
RUN apt update && apt upgrade -y
# 直接将工作目录设置为manage.py所在的项目根目录
WORKDIR /app/djangodocker
# 复制项目文件到当前工作目录
COPY . .
# 按需创建静态、媒体目录
RUN mkdir -p ../static-folder ../media-folder
# 安装依赖
RUN pip3 install --no-cache-dir -r requirements.txt
RUN chmod +x entrypoint.sh
ENTRYPOINT ["./entrypoint.sh"]

调整后docker-compose的command可直接写为：

command: gunicorn djangodocker.wsgi:application --bind 0.0.0.0:8000

通用排查方法 #

后续遇到同类模块找不到的问题，可按以下步骤定位：

1. 启动容器进入交互模式查看实际路径：docker run --rm -it --entrypoint bash dev-project/django
2. 执行pwd、ls确认目录结构是否符合预期
3. 执行python3 -c "import sys; print(sys.path)"查看Python搜索路径
4. 手动测试模块导入：python3 -c "import djangodocker.wsgi"，根据报错调整路径即可

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