Python包spark_map安装后出现ModuleNotFoundError求助

问题概述 #

开发的spark_map包已发布至TestPyPI，执行pip install -i https://test.pypi.org/simple/ spark-map==0.2.76安装无报错，pip list显示包已安装，且安装路径在Python的sys.path中，但新终端启动Python执行import spark_map时触发ModuleNotFoundError。本地包根目录下可正常导入，尝试过src目录结构、虚拟环境安装，问题仍存在。

系统信息：Windows10，Python3.10.9，spark_map版本0.2.76

排查与解决步骤 #

1. 验证TestPyPI包内容完整性 #

登录TestPyPI找到你的spark-map包，下载对应版本的.whl或.tar.gz包文件，解压后检查：

• 确认解压目录中存在spark_map文件夹，且内部包含__init__.py及其他模块文件
• 若采用src结构，确认src目录下存在spark_map文件夹，且打包时被正确包含

2. 检查pyproject.toml配置正确性 #

重点核对pyproject.toml的核心配置项：

• project.name必须为spark-map（PyPI允许包名带短横线，对应模块名为下划线格式spark_map）
• 包路径配置需匹配你的项目结构：
  • 非src结构：packages = ["spark_map"]
  • src结构：需设置package-dir并指定查找路径：

    [tool.setuptools.package-dir]
    "" = "src"
    
    [tool.setuptools.packages.find]
    where = ["src"]
    

• 确认project.scripts或entry-points未错误覆盖模块路径

3. 检查安装后的文件实际状态 #

打开Python的site-packages目录（Python310\lib\site-packages）：

• 确认存在spark_map文件夹，且内部文件完整
• 检查spark_map-0.2.76.dist-info元数据文件夹是否存在
• 若wheel安装有问题，尝试安装源码包：

  pip install -i https://test.pypi.org/simple/ spark-map==0.2.76 --no-binary :all:
  

4. 确保Python与pip环境一致 #

在新终端执行以下命令，验证使用的Python和pip属于同一环境：

python --version
pip --version

若路径不一致，使用绝对路径执行安装和测试：

# 替换为你的Python安装路径
C:\Python310\python.exe -m pip install -i https://test.pypi.org/simple/ spark-map==0.2.76
C:\Python310\python.exe
>>> import spark_map

5. 排查命名冲突 #

• 确认当前工作目录下无同名的spark_map.py文件或spark_map文件夹
• 检查其他已安装包是否存在同名模块

6. 重新打包上传TestPyPI #

若以上步骤均无问题，可能是打包或上传时出现异常：

1. 清理本地打包缓存：删除dist、build、*.egg-info文件夹
2. 重新打包：

   python -m build
   

3. 重新上传至TestPyPI（确保twine为最新版本）：

   python -m twine upload --repository testpypi dist/*
   

4. 等待几分钟后重新安装测试

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