Conda环境pip安装GitHub包后非项目目录导入报ModuleNotFoundError

架构老林

2026-8-28

问题根因

你当前环境的site-packages目录下仅存在my_package-1.0.dist-info元数据文件夹，没有实际的my_package代码目录，这是导入失败的核心原因。
之所以在项目文件夹内能正常导入，是因为Python运行时会自动把当前执行脚本的所在目录加入sys.path，优先读取本地的项目源码；离开项目目录后，本地源码路径不再被纳入搜索范围，自然就找不到模块了。
另外pip show命令读取的是dist-info目录下存储的元数据，哪怕实际代码没有被正确安装，只要元数据文件夹存在就会正常返回包信息，这也是你之前排查时误以为包已经完整安装的原因。

修复步骤

第一步：检查仓库目录结构
确保GitHub仓库根目录的结构符合setuptools的打包要求，setup.py必须和存放代码的my_package文件夹平级，且my_package文件夹内必须存在__init__.py文件（文件可以为空，作用是标记该目录为Python可导入包），正确结构参考：
```
仓库根目录/
├── setup.py
└── my_package/
    ├── __init__.py
    ├── 其余业务代码文件.py
```
如果你的代码存放在src这类子目录下，手动写packages=['my_package']会找不到代码，建议改用自动查找逻辑。

第二步：修正setup.py的错误
你当前的setup.py存在两处问题：一是python_requires拼写错误（写成了python_requieres，会导致Python版本限制不生效），二是手动写packages列表容易出现路径匹配失败的问题，修正后参考：

from setuptools import setup, find_packages

setup(name='my_package',
      version='1.0',
      description='My super cool package',
      url='https://github.com/my_name/my_package',
      packages=find_packages(), # 自动扫描目录下的可导入包，避免手动配置漏匹配
      python_requires='>=3.9', # 修正拼写，建议加>=兼容更高的Python3版本
      install_requires=[
            'some_package==1.0.0'
      ])

第三步：修正安装命令语法
你之前用的安装命令多了多余的单引号，正确的Git包安装格式为：
```
pip install git+https://github.com/my_name/my_package
```
第四步：清理旧安装后重装
先卸载之前安装的无效包：
```
pip uninstall -y my_package
```
把修正后的代码推送到GitHub仓库后，重新执行安装命令即可。安装完成后可以去site-packages目录确认，此时会同时存在my_package-1.0.dist-info元数据文件夹和my_package代码文件夹，离开项目目录后导入就不会再报错。

小提示：推送到远程前可以先在本地项目根目录执行pip install .做本地安装测试，确认site-packages内存在对应代码文件夹后再推远程，能减少反复调试的成本。

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