PyPi自定义包安装后触发ModuleNotFoundError的求助

一、先确认Python环境匹配 #

出现ModuleNotFoundError最常见的原因是运行代码的Python环境和安装包的环境不一致：

• 在测试代码开头添加以下内容，查看当前运行环境的Python路径：

  import sys
  print(sys.executable)
  

• 在终端执行pip --version，对比输出中的Python路径，确认两者完全一致。
• 如果路径不同，使用对应环境的pip重新安装包，比如：

  # 替换为你代码运行环境的Python路径
  /path/to/your/python -m pip install bsl_translator
  

二、修正包结构与导入路径不匹配的问题 #

你的setup.py中name="bsl_translator"是PyPi上的分发包名称，但Python导入时的模块名由你src目录下的实际包文件夹名称决定：

当前问题 #

从你的包结构和__init__.py内容来看，src目录下的实际包名是translator_fingerspelling，而非bsl_translator。所以安装后，正确的导入方式应该是：

from translator_fingerspelling import FingerSpelling

若要实现from bsl_translator import FingerSpelling的导入方式 #

需要调整包结构，步骤如下：

1. 将src目录下的translator_fingerspelling文件夹重命名为bsl_translator
2. 调整bsl_translator/__init__.py的内容：
   • 如果FingerSpelling类在bsl_translator目录下的某个模块（比如translator_fingerspelling.py）中，修改为：

     from .translator_fingerspelling import FingerSpelling
     

   • 如果FingerSpelling类直接在__init__.py中，保持原有逻辑即可
3. 重新构建并上传包到PyPi，或本地重新安装：

   pip install . --force-reinstall
   

三、其他排查点 #

• 清理Python模块缓存：删除项目目录和site-packages中对应包的__pycache__文件夹
• 本地开发时确保使用pip install -e .（可编辑模式）安装，避免路径混乱
• 检查setup.py的find_packages配置：find_packages(where="src")会自动识别src目录下所有包含__init__.py的文件夹作为包，确保你的目标包在src目录下且存在__init__.py

内容的提问来源于stack exchange，提问作者Miguel García