通过setup.py安装Python包后导入出现ModuleNotFoundError问题求助

问题核心原因 #

你遇到的问题是两个常见的Python打包误区叠加导致的：

1. setup.py中name字段是PyPI平台展示、pip安装时使用的包名，和实际Python代码中import时用的模块名没有强制对应关系
2. 你的实际源码包目录名不符合Python标识符规范，且打包工具没有正确识别到你的源码，导致安装的是一个空包，自然无法导入

解决方案 #

按以下步骤操作即可解决：

• 第一步：重命名包含__init__.py的源码目录
  Python的模块名只允许包含字母、数字、下划线，不能使用短横线。你现在的源码目录名为my-package，首先要将它改为你想要的导入名，比如你想import new_package，就将目录名改为new_package，修改后目录结构如下：

  my-package  # 项目根目录名称不影响导入，可保留原有名称
  ├── README.md  
  ├── LICENSE  
  ├── .gitignore  
  ├── setup.py  
  └── new_package  # 实际源码目录，名称和导入名完全一致，用下划线代替短横线
      ├── __init__.py
      └── other_files.py
  

• 第二步：调整setup.py的包扫描配置
  普通单包结构使用find_packages()即可完成源码识别，修改setup.py中对应配置行：

  packages=find_packages(), # 替换原有的find_namespace_packages()
  

• 第三步：清理旧的安装包并重新安装
  依次执行以下命令：

  # 卸载之前错误安装的空包
  pip uninstall -y new-package
  # 重新执行可编辑模式安装
  python -m pip install -e .
  

• 第四步：验证导入
  执行以下命令验证导入是否正常：

  python -c "import new_package; print('导入成功')"
  

补充说明 #

如果你希望导入时使用import my_package，只需要把源码目录名改为my_package即可，不需要修改setup.py中的name字段，pip安装时仍然使用pip install new-package即可，两者互不影响。

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