Docker部署Python项目遇ModuleNotFoundError: No module named 'app'问题求助

问题场景 #

项目结构如下：

-- app
---- Module1
------ ClassM1.py
---- Module2
----- ClassM2.py
---- main.py
-- docker-compose.yml

通过docker-compose.yml将本地./app/挂载到容器内的/app/。

本地PyCharm开发环境中，main.py使用以下导入语句运行正常：

from app.Module1.ClassM1 import ClassM1
from app.Module2.ClassM2 import ClassM2

但代码部署到容器中运行时，出现错误：

"ModuleNotFoundError: No module named 'app'"

已尝试的解决方法：

• 在根目录创建__init__.py
• 执行export PYTHONPATH=.
• 在代码中导入sys并执行sys.path.append("./")

核心原因 #

本地PyCharm默认将包含app文件夹的项目根目录加入了Python路径，因此能识别app作为顶层模块；但容器内运行时，工作目录通常是/app（即main.py所在目录），此时Python的路径中没有app模块的父目录，无法找到app这个顶层模块。

可行解决方案 #

方案1：调整容器工作目录与PYTHONPATH #

修改docker-compose.yml，将容器工作目录设置为/（app文件夹的父目录），同时设置PYTHONPATH指向该目录：

services:
  # 替换为你的服务名称
  your-service:
    volumes:
      - ./app:/app
    working_dir: /
    environment:
      - PYTHONPATH=/

这样Python就能在路径中找到顶层的app模块，原有的绝对导入语句可以正常使用。

方案2：改用相对导入 #

因为容器内main.py位于/app目录，直接使用相对导入即可：

from Module1.ClassM1 import ClassM1
from Module2.ClassM2 import ClassM2

需要确保Module1和Module2目录下都存在空的__init__.py文件，让Python识别它们为子模块。

方案3：以模块方式启动脚本 #

如果希望保留绝对导入，可以在容器内以模块方式启动main.py，而不是直接运行脚本。确保容器工作目录为/，然后执行：

python -m app.main

这种启动方式会自动将当前目录（/）加入Python路径，使app模块被正确识别。

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