Python项目ModuleNotFoundError求助：src导入与测试导入冲突问题

核心原因 #

问题出在Python的模块查找逻辑上：

• 直接运行src/main.py时，Python会把src目录当作当前工作目录，因此无法识别src作为顶级包；
• 运行tests/test_main.py时，Python将包含src和tests的项目根目录当作工作目录，此时src是可识别的顶级包，但main.py里直接导入modules会失败，因为modules是src的子包而非顶级包。

具体解决方法 #

方法一：将项目根目录加入PYTHONPATH #

Python会从PYTHONPATH环境变量指定的路径中查找模块，把包含src和tests的项目根目录加入该路径，即可统一两种场景的导入逻辑：

• 临时设置（终端）：
  • Windows系统：set PYTHONPATH=你的项目根目录绝对路径
  • Linux/macOS系统：export PYTHONPATH=你的项目根目录绝对路径
    设置完成后，直接运行python src/main.py或python tests/test_main.py即可正常导入模块。
• 永久设置：将项目根目录路径添加到系统的PYTHONPATH环境变量中，后续每次打开终端都会自动生效。

方法二：统一导入语句格式 #

• 修改src/main.py的导入语句：把from src.modules.fileA import classOfFileA改为from modules.fileA import classOfFileA（因为main.py与modules同属src目录，可直接相对导入）。
• 保留tests/test_main.py的from src.main import *语句，确保项目根目录已在PYTHONPATH中，此时Python能识别src顶级包，同时main.py里的modules导入也会正常生效。

方法三：将项目安装为可编辑包 #

这种方式适合长期开发的项目，能彻底解决导入问题：

1. 在项目根目录创建setup.py文件，内容示例如下：

   from setuptools import setup, find_packages
   
   setup(
       name="your-project",
       version="0.1.0",
       packages=find_packages(where="src"),
       package_dir={"": "src"},
   )
   

2. 进入项目根目录，在终端运行命令：

   pip install -e .
   

3. 完成后，无论运行main.py还是测试文件，所有导入语句都能正常工作，无需额外设置路径。

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