Python包graphab4py已安装却无法导入，求问题排查方案

问题描述 #

• 开发Python包graphab4py并上传至PyPI，基于Python 3.11.3开发，设置兼容性要求为Python >=3.11
• 执行pip install graphab4py安装成功，但无法在Python脚本中导入该包（其他通过pip安装的包可正常导入）
• 搭建虚拟环境重复安装、导入操作，问题依旧
• 通过以下代码确认包已被识别：

for dist in __import__('pkg_resources').working_set:
    print(dist.project_name.replace('Python', ''))

输出结果包含graphab4py，但执行import graphab4py时仍报错：

ModuleNotFoundError: No module named 'graphab4py'

• 补充：安装目录下仅存在graphab4py-1.0.1.dist-info文件夹，无graphab4py包文件夹，安装过程无任何报错

核心原因及解决办法 #

1. 包构建配置错误（最可能原因） #

安装后没有生成对应包文件夹，说明打包时未将实际代码包含进去，问题出在构建配置文件上：

• 检查项目结构：确保项目根目录下存在与包名同名的graphab4py文件夹，且该文件夹内必须包含__init__.py文件（空文件也可）
• 修正构建配置：
  • 若使用setup.py，需确保packages参数正确指定要打包的内容，示例：

    from setuptools import setup, find_packages
    
    setup(
        name="graphab4py",
        version="1.0.1",
        packages=find_packages(),  # 自动识别所有含__init__.py的包
        # 其余配置项...
    )
    

  • 若使用pyproject.toml，需正确配置包路径：

    [tool.setuptools]
    packages = ["graphab4py"]
    

2. 打包时遗漏代码文件 #

• 检查源码包内容：执行python -m build生成dist目录，解压其中的.tar.gz文件，确认是否包含graphab4py文件夹
• 若使用MANIFEST.in，需添加规则确保包目录被包含：

  include graphab4py/*.py
  recursive-include graphab4py *
  

3. 版本兼容性验证 #

虽然已设置Python >=3.11，仍需确认构建包时使用的Python版本与安装环境一致，避免字节码不兼容问题（该情况报错通常不同，优先级低于配置问题）

验证流程 #

1. 在项目根目录执行python -m build重新构建包
2. 本地安装测试包：pip install dist/graphab4py-1.0.1.tar.gz（替换为实际版本号）
3. 启动Python会话尝试导入，若成功则说明之前上传到PyPI的包存在构建错误，重新上传正确构建的包即可

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