Python将父目录加入sys.path仍触发ModuleNotFoundError问题咨询

核心原因说明 #

你在parser目录下直接启动Python可以正常导入，是因为Python启动时会自动把当前工作目录加到sys.path搜索顺序的最顶端，不存在路径匹配异常问题。而手动追加父目录到sys.path失败，通常是以下几类原因导致： #

1. 重名模块优先级冲突 #

使用sys.path.append()是把路径加到搜索列表的末尾，如果sys.path中排在c:\projects\parser前面的路径里存在其他名为tests的包/模块，Python会优先加载这个无关的tests，自然找不到它下面的utils子模块。
排查方法：在追加路径后执行以下代码确认：

import sys
# 确认目标路径已成功加入sys.path
print(sys.path)
# 导入tests并查看它的实际加载路径
import tests
print(tests.__file__)

如果输出的tests.__file__不是c:\projects\parser\tests\__init__.py，就说明匹配到了重名模块。
解决方法：把sys.path.append('c:\\projects\\parser')改成sys.path.insert(0, 'c:\\projects\\parser')，将你的项目路径加到搜索顺序的最前面即可。 #

2. 路径字符串与实际路径不匹配 #

Windows系统虽然默认不区分大小写，但如果你的NTFS分区对应目录开启了大小写敏感、或者Python运行在WSL兼容环境下，你代码中写的小写c:\\projects\\parser和实际路径C:\Projects\parser（注意Projects首字母大写）会被识别为不同路径，导致Python找不到对应目录下的tests包。
排查方法：追加路径后增加路径存在性校验：

import os
print(os.path.exists('c:\\projects\\parser\\tests'))

如果返回False，把路径字符串改成和实际磁盘路径完全一致的写法即可。 #

3. 特殊场景：init.py读取权限异常 #

极少数情况是tests或tests/utils目录下的__init__.py文件没有当前用户的读取权限，导致Python无法将目录识别为合法的可导入包，手动打开对应文件确认是否能正常读取即可排除该问题。

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