单文件Python包安装失败求助：为何重命名__init__.py后才生效？

1. 原方案失败的核心原因：不符合Python包的结构要求 #

你最初的项目结构是项目根目录直接放置__init__.py，这不符合Python对「包」的定义：Python的包必须是一个命名目录，目录下包含__init__.py文件（现代Python也支持无__init__.py的命名空间包，但你的场景不适用）。

当你用pip install安装时，setuptools无法将这个孤立的__init__.py关联到名为mypackage的包上——它既不是标准的包目录结构，也没有在配置中明确声明为模块，最终导致pip虽然提示安装成功，但实际上没有在site-packages下生成预期的mypackage目录，自然无法通过python -m mypackage调用（-m参数要求目标是可识别的包或模块名）。

2. 重命名后成功的逻辑：切换为「单模块」配置 #

你将__init__.py重命名为myproject.py并修改pyproject.toml的[tool.setuptools]配置后，本质是把项目从「尝试创建包」改成了「发布单模块」：

• 重命名后的myproject.py是一个独立的Python模块文件
• 你在配置中应该添加了py_modules = ["myproject"]这类声明，明确告诉setuptools要安装这个单模块
• setuptools会将myproject.py直接复制到site-packages下，并生成对应的元数据文件，让Python能识别到这个模块，因此可以正常导入和运行。

3. 若想做成「包」而非单模块的正确姿势 #

如果你的目标是创建名为mypackage的可运行包，正确的项目结构应该是：

你的项目根目录/
├── pyproject.toml
└── mypackage/
    └── __init__.py

然后在pyproject.toml中配置：

[tool.setuptools]
packages = ["mypackage"]

这样pip安装时会在site-packages下生成mypackage目录，包含__init__.py，就能通过python -m mypackage正常调用了。

内容的提问来源于stack exchange，提问作者Mikhail T.