使用Poetry构建的Python自定义包无法导入：ModuleNotFoundError

关于空__init__.py的合理性 #

空的__init__.py是完全合理的，它仅用于标识该目录为Python可识别的包目录，不需要任何代码即可正常实现模块导入功能。

核心问题排查：包分发名与模块导入名不匹配 #

你的报错ModuleNotFoundError: No module named 'sampleproject'最可能的原因是混淆了PyPI分发包名和Python实际模块名：

• pyproject.toml中[tool.poetry]下的name = "sampleproject"是这个包在仓库上的分发包名称（即pip install sampleproject时的包名）；
• 而packages = [{include="src/sample"}]配置指定的是要安装到Python环境中的实际模块名为sample，而非sampleproject。

你应该尝试导入sample而非sampleproject：

>>> import sample

进一步排查方向 #

1. 验证安装后的模块结构 #

找到你的Miniconda环境的site-packages目录（可通过conda env list查看环境路径，再进入lib/pythonX.X/site-packages），检查其中是否存在sample目录而非sampleproject目录，这直接确认了实际可导入的模块名。

2. 检查构建产物的内部结构 #

解压你生成的wheel包sampleproject-3.0.0-py3-none-any.whl，查看内部目录结构：如果是sample/开头，说明模块名确实是sample；如果期望模块名为sampleproject，需要调整目录结构或配置。

3. 修正配置以匹配期望的导入名 #

如果希望最终能通过import sampleproject导入，需要做以下调整：

• 调整目录结构：将src/sample重命名为src/sampleproject；
• 同步修改配置：将packages配置改为：

  packages = [{include="sampleproject", from="src"}]
  

• 同步修改脚本配置：如果保留[project.scripts]，需要更新为：

  sample = "sampleproject:main"
  

4. 确认Poetry构建流程正确 #

确保你是通过以下流程构建并安装的：

# 构建包
poetry build
# 安装到当前环境
pip install dist/sampleproject-3.0.0-py3-none-any.whl

避免使用poetry install开发模式与pip install混合导致的环境不一致问题。

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