Python本地模块与第三方依赖包同名导入冲突问题排查

这个报错的核心是Python的模块查找规则和模块缓存机制导致的命名冲突：

• Python运行脚本时，会自动把执行入口脚本所在的项目根目录放到sys.path（模块搜索路径列表）的最高优先级位置，比所有第三方库的安装路径优先级都高。你在项目根目录下写了utils.py，当代码执行import utils时，会优先加载你本地的这个单文件模块，而不是其他路径下同名的utils包。
• Python有全局模块缓存机制：所有已经加载过的模块都会存在sys.modules字典里，后续任何位置再导入同名模块时，会直接从缓存里取已经加载的对象，不会再重新遍历sys.path搜索其他位置的同名模块。你尝试用import utils as ut改别名没有效果，是因为别名只修改当前作用域的变量绑定，模块在sys.modules里注册的名字依然是utils，缓存里存的还是你本地的单文件utils。
• torch.hub.load加载YOLOv5时，不会做独立的模块隔离，而是直接在当前Python进程中执行缓存目录里的YOLOv5源码。当YOLOv5代码执行from utils.dataloaders import xxx时，会直接命中缓存里你本地的utils.py，但这个单文件模块下根本没有dataloaders子模块，同时Python不会再继续搜索其他路径下的utils包，就会抛出你看到的报错。

• （最推荐）遵循Python项目开发最佳实践，不要使用utils.py、config.py、common.py这类过于通用、极易和第三方依赖重名的顶层文件名，把本地工具模块改成带项目辨识度的名字，比如local_utils.py、project_utils.py，从根源上避免命名冲突。
• 优化项目结构，不要把工具函数直接放在顶层目录，而是放到以项目名命名的专属包下，比如建立your_project_name/utils.py目录结构，导入时使用from your_project_name import utils，此时模块注册名为your_project_name.utils，完全不会和顶层的utils模块产生冲突。
• （不推荐，仅作临时方案）手动调整sys.path顺序和模块缓存，在导入本地utils之前先加载YOLOv5的依赖包，再切换回本地路径导入自己的模块，示例代码如下：

import sys
import os
import torch

# 提前将YOLOv5缓存目录加入搜索路径最高优先级
yolo_cache = os.path.expanduser("~/.cache/torch/hub/ultralytics_yolov5_master")
sys.path.insert(0, yolo_cache)
# 预加载YOLOv5的utils包到缓存
import utils as yolo_utils
# 移除YOLOv5路径，切回项目根目录优先级
sys.path.pop(0)
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
# 清除缓存中已加载的utils，重新导入本地模块
if "utils" in sys.modules:
    del sys.modules["utils"]
import utils

if __name__ == "__main__":
    print("Foo")
    utils.bar()
    model = torch.hub.load("ultralytics/yolov5", "yolov5s")

注意：该方案存在兼容隐患，后续如果需要同时调用本地utils和YOLOv5的utils会出现命名冲突，非特殊场景不建议使用。

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