Python包导入报错：无法从mypackage导入mod（疑似循环导入）

问题场景 #

你的代码仓库目录结构：

mypackage/
    __init__.py
    multiplication.py
    mod/
        __init__.py
        addition.py

各文件内容：

• mod/addition.py：

def add(a,b):
    return a+b

• mod/__init__.py：空文件
• multiplication.py：

def add(a,b):
    return a*b

当mypackage/__init__.py仅导入multiplication时可正常使用，但添加from . import mod后，触发如下报错：

from . import mod
ImportError: cannot import name 'mod' from partially initialized module 'mypackage' (most likely due to a circular import) (/usr/local/lib/python3.12/site-packages/mypackage/__init__.py)

排查与解决方案 #

1. 先排查循环依赖 #

首先检查mod目录下的所有文件（mod/__init__.py、mod/addition.py），确认是否存在**直接或间接导入mypackage**的代码。如果有，这类导入会导致循环依赖，必须移除。

2. 调整导入方式 #

若确认无循环依赖，可通过以下方式解决导入顺序问题：

• 直接导出功能（推荐）
  修改mypackage/__init__.py，直接导入子模块的具体函数，用户无需关心内部结构：

  from .multiplication import add as multiply
  from .mod.addition import add
  

  使用时直接调用mypackage.multiply(a,b)和mypackage.add(a,b)即可。

• 使用绝对导入
  替换相对导入为绝对导入，避免模块加载时的歧义：

  import mypackage.multiplication
  import mypackage.mod
  

• 延迟导入
  若包有初始化逻辑，可将导入放在函数内部，延迟到实际使用时加载：

  from . import multiplication
  
  def get_add_function():
      from .mod import addition
      return addition.add
  

3. 验证安装正确性 #

检查Docker镜像中包的安装方式，建议使用pip install .正式安装或pip install -e .开发模式，确保包结构被Python正确识别。同时确认安装路径下没有同名的mypackage文件夹干扰。

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