如何配置Python setuptools将根目录模块安装为单个包

你当前采用的是项目根目录直接作为包内容目录的扁平结构，没有在根目录下嵌套同名mypackage子目录，需要显式配置包路径映射，才能同时支持「复制目录免安装直接导入」和「pip安装为全局包」两种使用方式。

核心配置如下，直接替换你setup.cfg里的对应内容即可：

# setup.cfg
[options]
package_dir =
    mypackage = .
packages = mypackage

配置逻辑说明 #

• package_dir的规则是包名 = 对应文件路径，mypackage = .的含义是：名为mypackage的Python包，所有代码内容就存放在setup.cfg所在的当前目录，不需要额外找同名子目录。
• packages = mypackage显式声明当前要构建的是单个名为mypackage的包，不要用自动扫描规则（find:），避免把.git等无关目录识别为包内容。

效果验证 #

1. 免安装场景：把整个mypackage文件夹复制到任意父项目根目录，因为文件夹内自带__init__.py，Python会直接识别为可导入包，无需修改PYTHONPATH、无需执行安装，直接写from mypackage import something就能正常使用，完全匹配你的使用需求。
2. 安装场景：在mypackage目录下执行pip install .时，setuptools会将当前目录下的__init__.py、module1.py、module2.py等包文件安装到对应Python环境的第三方包目录，安装完成后全局都可导入mypackage。

必要补充 #

请确保同目录下的pyproject.toml配置了正确的setuptools构建后端，否则打包会失败，最小可用配置为：

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

注意不要在mypackage根目录存放和包逻辑无关的Python文件，这类文件会被一并打包进最终的安装包中。

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