如何在site-packages安装同名顶层模块的子包且不覆盖原有结构？

可行性结论 #

可行，但有个关键前提：你现有的test1必须是标准Python包——也就是site-packages/test1目录下得有__init__.py文件（哪怕是空的）。如果只是个空文件夹没这个文件，Python不会把它当成包，后续操作肯定出问题。

不用命名空间的实现步骤 #

1. 先确认原有test1的状态 #

检查site-packages/test1里有没有__init__.py，没有的话手动建一个空文件就行，这是Python识别它为包的必要条件。

2. 新包的本地结构要搭对 #

新包的本地开发目录得是这个样子：

new_submodule_package/
├── setup.py
└── test1/
    └── subModule1/
        ├── __init__.py
        └── （你的业务代码文件，比如utils.py）

重点：新包的test1目录下别加自己的__init__.py，不然安装时会覆盖原有test1里的这个文件。

3. 新包的setup.py要精准配置 #

在setup()里用packages参数明确只打包子模块，别把顶层test1也包进去。示例代码：

from setuptools import setup, find_packages

setup(
    name="test1-submodule1",
    version="0.1.0",
    # 只包含subModule1及其子模块，避免打包顶层test1
    packages=find_packages(include=["test1.subModule1", "test1.subModule1.*"]),
    # 其他比如author、description之类的信息按需填
)

用find_packages(include=...)可以精准筛选要打包的内容，确保不会把空的test1/__init__.py塞进安装包。

4. 安装时别瞎加参数 #

安装新包的时候，别用--force-reinstall或者--upgrade --force-reinstall这类强制覆盖的参数，不然可能把原有test1的东西搞坏。直接用pip install .（本地安装）或者从PyPI拉取安装就行，pip会自动把subModule1目录加到已有的test1下面，不会覆盖原有文件。

验证是否成功 #

安装完之后，打开Python交互环境测一下：

import test1
import test1.subModule1

# 看原有test1的__init__.py路径是否正常
print(test1.__file__)
# 看subModule1的路径是否在原有test1目录下
print(test1.subModule1.__file__)

如果两个模块都能正常导入，路径也符合预期，就说明成功了。

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