Python包经pip安装至site-packages后无法导入子模块求助

这个问题我之前踩过坑！很可能是你的包在打包环节没正确配置子模块，或者缺少关键的__init__.py文件，导致pip安装后子模块没有被正确识别或复制到site-packages里。下面一步步给你排查和解决：

1. 先检查包的目录结构与__init__.py #

首先确认你的包结构是否规范，典型的结构应该是这样的：

mypackage/
├── mypackage/          # 核心包目录
│   ├── __init__.py     # 根包必须有这个文件（哪怕是空的）
│   ├── submodule1/
│   │   ├── __init__.py # 子模块目录也建议加上
│   │   └── moduleA.py
│   └── submodule2/
│       ├── __init__.py
│       └── moduleB.py
└── setup.py            # 或 pyproject.toml 打包配置文件

• 虽然Python 3.3+支持无__init__.py的隐式命名空间包，但很多打包工具（比如setuptools）还是依赖这个文件来识别子模块。如果你的子模块目录没有__init__.py，pip安装时可能不会把这些子模块包含进去，直接补上空的__init__.py就能解决大部分问题。

2. 重点检查打包配置文件（setup.py / pyproject.toml） #

这是最常见的问题根源！很多人写打包配置时只指定了根模块，完全没把自模块包含进去，导致安装后site-packages里只有根包，子模块根本没被复制。

如果你用setup.py： #

一定要用find_packages()自动扫描所有子模块，或者手动列出所有子包：

from setuptools import setup, find_packages

setup(
    name="mypackage",
    version="0.1.0",
    packages=find_packages(),  # 关键！自动查找所有带__init__.py的子包
    # 其他配置：author, description, install_requires等...
)

如果手动指定packages参数，别漏了子模块：

packages=["mypackage", "mypackage.submodule1", "mypackage.submodule2"]

如果你用现代的pyproject.toml： #

确保正确配置packages字段，要么手动列出，要么用find自动扫描：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "0.1.0"
# 方式1：自动扫描mypackage下所有子包
packages = [{ find = "mypackage" }]
# 方式2：手动列出所有包
# packages = ["mypackage", "mypackage.submodule1", "mypackage.submodule2"]

3. 验证安装后的文件结构 #

安装后先确认子模块是否真的被安装到了site-packages里：

1. 运行命令找到包的安装路径：

python -c "import mypackage; print(mypackage.__file__)"

2. 打开这个路径所在的目录，看看submodule1、submodule2这些子目录是否存在。
   如果子模块目录没在里面，说明打包时确实没包含它们，回到第二步调整配置即可。

4. 特殊情况：命名空间包 #

如果你的包是跨目录的命名空间包（比如多个不同项目共享同一个顶级包名），那需要用find_namespace_packages()代替find_packages()，并且子模块目录不要加__init__.py（或者添加符合命名空间规范的__init__.py）。不过这种场景比较少见，普通包一般用不到。

示例setup.py配置：

from setuptools import setup, find_namespace_packages

setup(
    name="mypackage",
    version="0.1.0",
    packages=find_namespace_packages(include=["mypackage.*"]),
)

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