github 上发布的 python 包通过 pip install git+https://... 成功安装，但 import spellcheck 报 modulenotfounderror，根本原因常是包目录名与导入名不一致（如大小写或路径结构不匹配），而非安装失败。
github 上发布的 python 包通过 pip install git+https://... 成功安装，但 import spellcheck 报 modulenotfounderror，根本原因常是包目录名与导入名不一致（如大小写或路径结构不匹配），而非安装失败。
在 Python 中，pip install 安装的包名（即 setup.py 中的 name= 字段）仅用于分发和元数据管理，真正决定 import 语句能否成功的是项目源码的目录结构——特别是顶层包目录的名称及其是否包含有效的 __init__.py 文件。
以你的仓库 loictonneau75/spellcheck 为例：
- pip show spellcheck 显示安装成功，说明 setup.py 中 name="spellcheck" 正确，PyPI 兼容性无误；
- 但实际代码仓库根目录下是一个名为 SpellCheck/ 的文件夹（首字母大写），其内部包含 __init__.py 和 spellcheck.py；
- 因此，合法的导入路径是 from SpellCheck.spellcheck import SpellCheck，而非 import spellcheck。
✅ 正确用法（当前结构）：
from SpellCheck.spellcheck import SpellCheck
# 使用示例
sp = SpellCheck("your_api_key", "fr")
print(sp("coocou")) # → "coucou"⚠️ 常见误区：
立即学习“Python免费学习笔记（深入）”；
- 认为 setup.py 中的 name="spellcheck" 会自动创建同名可导入模块；
- 忽略文件系统大小写敏感性（macOS/Linux 区分 SpellCheck 与 spellcheck，Windows 虽不敏感但 Python 导入机制仍严格匹配目录名）；
- 未检查 pip install -e .（开发模式）与 pip install git+... 对路径解析的一致性。
? 解决方案（推荐）：
统一命名，使包目录名与期望导入名完全一致：
- 将本地仓库中的目录 SpellCheck/ 重命名为 spellcheck/；
- 更新所有内部引用（如 from SpellCheck.spellcheck import ... → from spellcheck.spellcheck import ...）；
- 确保 spellcheck/__init__.py 正确导出接口（例如 from .spellcheck import SpellCheck）；
- 重新安装（建议加 -e 开发模式便于调试）：
pip uninstall spellcheck -y pip install -e . # 或从 GitHub 重装 pip install -e "git+https://www.php.cn/link/b3e31e79453990477407f7baa2c27d70.git#subdirectory=."
? 验证是否修复：
import spellcheck # ✅ 应不再报错 print(spellcheck.__file__) # 查看实际加载路径，确认指向 spellcheck/ 目录
? 总结：Python 的模块导入机制只认文件系统中的包目录名，与 setup.py 的 name 字段无关。发布前务必确保：
- 顶层包目录名小写、无特殊字符、与预期 import 名完全一致；
- 目录内含 __init__.py（即使为空）；
- setup.py 的 packages=find_packages() 或显式列出该目录（如 packages=["spellcheck"]）。
遵循这一原则，即可避免 90% 的“安装成功却无法导入”问题。
