导入异常：无法从部分初始化的my_package导入my_sub_package（疑似循环导入）

包结构 #

my_package/
    setup.py
    my_package/
        __init__.py
        module1.py
        my_sub_package/
            __init__.py
            module2.py

各文件内容 #

my_package/init.py #

from . import my_sub_package
from .module1 import *

my_package/my_sub_package/init.py #

from .module2 import *

setup.py #

from setuptools import setup

setup(
    name='My Package',
    packages=['my_package'],
    version='1.0.0'
)

问题现象 #

在包的父目录下执行import my_package可以正常运行，但通过pip3 install my_package/ --upgrade --force-reinstall安装后，在其他目录执行该导入语句时出现报错：

ImportError: cannot import name 'my_sub_package' from partially initialized module 'my_package' (most likely due to a circular import) (<PYTHON_PATH>/lib/python3.11/site-packages/my_package/init.py)

问题核心是setup.py的打包配置遗漏了子包，导致安装后site-packages里的包结构不完整：

1. 打包配置的问题
   当前setup.py里packages=['my_package']只声明了主包，没有包含子包my_sub_package。用pip安装时，setuptools只会打包主包内的文件，子包文件夹不会被同步到site-packages目录。这就导致Python导入时找不到子包，进而误报成“循环导入”的错误。

2. 本地能运行的原因
   在包的父目录下时，Python会从当前目录的完整包结构里检索子包，所以能正常找到my_sub_package，但安装后site-packages里的包结构缺失，就会触发报错。

3. 修复方法
   有两种简单的修复方式：

   • 方式一：手动列出所有包和子包，修改setup.py的packages参数：

     from setuptools import setup
     
     setup(
         name='My Package',
         packages=['my_package', 'my_package.my_sub_package'],
         version='1.0.0'
     )
     

   • 方式二：使用find_packages()自动扫描所有包和子包（更适合复杂项目）：

     from setuptools import setup, find_packages
     
     setup(
         name='My Package',
         packages=find_packages(),
         version='1.0.0'
     )
     

   修改后重新执行安装命令，就能正常导入包了。

另外，如果module1.py里存在导入my_sub_package的代码，会加重这种“循环导入”的误判，但根源还是子包未被正确打包。

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