个人Python库项目中mypy报重复模块错误：--explicit-package-bases与setuptools配置哪种方案更推荐？

咱们先搞清楚为啥会出现这个错误：在GitHub CI环境里，你大概率执行了类似pip install .的命令来安装依赖，这时候setuptools会在build/lib目录下生成一份hello包的副本。而mypy默认会扫描所有它能找到的Python模块，于是同时发现了根目录的hello和build/lib里的hello，就抛出了“重复模块”的错误。

接下来咱们拆解两个解决方案的逻辑，再看哪个更适合你的场景：

方案1：使用--explicit-package-bases参数 #

这个是mypy原生的解决方案，它的作用是告诉mypy：要显式基于目录下的__init__.py来识别包的根目录，而不是默认的模糊扫描模式。开启这个参数后，mypy会精准识别出根目录的hello是你的项目包，不会把build/lib里的副本当成另一个独立的包根，自然就不会报重复了。

它的优势很明显：

• 完全聚焦在mypy的问题上，不需要修改任何打包相关的配置，符合你“不想发布/分发这个库”的需求
• 操作简单，只需要在CI的mypy命令里加上这个参数就行，比如：mypy --explicit-package-bases .

方案2：添加[tool.setuptools] py-modules = []配置 #

这个是从setuptools的层面解决问题。py-modules参数本来是用来指定项目中的独立模块文件（不是包的那种单个.py文件），把它设为空列表，就是告诉setuptools：我的项目没有独立模块，只有包结构（也就是hello这个包）。这样当setuptools执行安装操作时，就不会在build/lib里生成多余的包副本，从根源上避免了mypy扫描到重复模块。

它的适用场景是：

• 如果你之后可能需要偶尔打包测试（哪怕只是本地用）
• 希望项目的打包配置更规范，避免其他潜在的打包相关问题

推荐方案 #

结合你说的“只是个人Python库，不需要发布/分发，只需要跑pytest和mypy”的场景，更推荐使用--explicit-package-bases。理由如下：

1. 它完全贴合你的需求，不需要碰你本来就用不上的打包配置，避免过度配置
2. 直接针对mypy的扫描逻辑调整，解决问题更精准，不会引入额外的打包相关行为
3. 操作成本更低，只需要修改CI中的mypy命令即可

当然，如果之后你有打包的需求，再切换到py-modules = []的配置也完全没问题。

备注：内容来源于stack exchange，提问作者Abhijit Sarkar