如何正确配置Python包的__init__.py以解决导入报错问题

问题根源 #

你的报错来自两个核心问题：

1. setup.py中仅指定了根包test_package，未包含所有子包（dir1、dir1.dir3、dir2），导致打包安装时这些子目录未被正确纳入包中。
2. 根目录的__init__.py未导入子包/模块，因此import test_package后无法直接通过test_package访问子层级的内容。

步骤1：修复setup.py，确保所有子包被打包 #

修改setup.py，使用find_packages()自动识别所有带__init__.py的子包，替代手动指定包列表：

import os
from setuptools import setup, find_packages
from test_package import __version__

if __name__ == '__main__':
    setup(
        name='test_package',
        python_requires='>=3.11',
        version=os.getenv('PACKAGE_VERSION', __version__),
        packages=find_packages(),
    )

find_packages()会自动扫描当前目录，将所有包含__init__.py的子目录识别为包，确保打包时不会遗漏dir1、dir2等子结构。

步骤2：配置各级__init__.py，实现层级导入 #

通过在__init__.py中导入子包/模块，让顶层包可以直接访问子层级内容：

1. 根目录/test_package/__init__.py #

添加子包导入语句：

__version__ = '0.1.0'

# 导入子包，使test_package.dir1、test_package.dir2、test_package.main可直接访问
from . import dir1
from . import dir2
from . import main

2. /test_package/dir1/__init__.py #

导入该目录下的子模块和子包：

from . import code2
from . import dir3

3. /test_package/dir1/dir3/__init__.py #

导入该目录下的模块：

from . import code3

4. /test_package/dir2/__init__.py #

导入该目录下的模块：

from . import code

验证修复 #

重新执行打包安装命令：

python setup.py sdist
python setup.py install

在Python交互环境中测试：

>>> import test_package
>>> print(test_package.dir2.code.test_code())
Hello
>>> print(test_package.main.test_code_main())
Hello dude. Whatsapp!!

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