pip install .仅生成dist-info无法导入Python包的问题排查

看起来你遇到的问题是本地安装包后，虽然pip能识别到包，但实际的模块文件并没有被安装到site-packages目录里——这也是为什么你只看到dist-info文件夹，却无法import的原因。结合你的setup.py代码和描述，我整理了几个最可能的原因和对应的解决方案：

1. 补充必填的version参数 #

你的setup.py里注释掉了version参数，而这是setuptools要求的必填项。缺失版本号可能导致安装过程不完整：虽然pip会生成dist-info文件夹，但不会复制实际的包代码。

修改setup.py，添加一个有效的版本号：

setup(
    name=NAME,
    version='0.1.0',  # 添加这行，替换成你的版本号
    description=DESCRIPTION,
    # ... 其他参数不变
)

2. 确认项目目录结构正确 #

确保你的包目录和setup.py处于同一层级，并且目录内包含__init__.py文件（Python 3.3+支持无__init__.py的命名空间包，但为了兼容性和明确性，建议加上）。正确的结构应该是这样的：

your-project-folder/
├── setup.py
└── <package>/       # 这里的目录名就是你要import的包名
    ├── __init__.py
    └── your_module.py

注意：setup.py里的NAME参数是包在PyPI上的名称，和实际的包目录名可以不一样，但import时必须使用包目录名。如果两者不一致，你用NAME的值去import自然会报错。

3. 验证find_packages()是否真的找到包 #

虽然你说find_packages()能找到包，但最好直接验证它的输出。在setup.py里添加一行打印语句：

print("Detected packages:", find_packages())
# 然后是setup(...)函数

运行pip install .，查看控制台输出。如果打印结果里没有你的包名，说明find_packages()没正确识别到包目录。这时候可以：

• 明确指定packages列表：packages=['<package>']（替换成你的包目录名）
• 如果包在子目录（比如src文件夹下），需要额外配置：

  packages=find_packages(where='src'),
  package_dir={'': 'src'},
  

4. 用verbose模式排查安装过程 #

运行pip install . -v（verbose模式），查看安装的详细日志。如果日志里没有类似copying <package>/__init__.py -> site-packages/<package>的记录，说明包代码根本没被复制——这时候就要回到packages参数的配置，确保它包含了你的包目录。

5. 尝试开发模式安装 #

如果上面的方法都没解决，试试开发模式安装：

pip install -e .

这种模式会在site-packages里创建一个指向你本地包目录的链接，而不是复制文件。如果这时候能正常import，说明你的包结构是对的，之前的问题可能是缓存或安装过程中的小bug导致的。

内容的提问来源于stack exchange，提问作者André Betz