从Bitbucket仓库安装自定义Python包后出现无法导入的问题

核心原理 #

本地pip install -e为可编辑安装模式，本质是在site-packages中创建指向本地源码目录的软链接，不会触发Python的打包文件筛选逻辑，所以只要本地文件存在就能正常运行。而从git远程仓库安装时，pip会自动执行打包流程，仅会打包配置文件中声明需要包含的文件，因此出现安装后空目录的问题基本都和打包配置或仓库文件完整性相关。

常见故障原因 #

• 打包配置文件未正确声明待打包的源码
  • 使用setup.py配置的项目：未正确设置packages参数（例如漏写需要打包的包目录，或用find_packages()时未传入正确的搜索路径），未开启include_package_data=True导致MANIFEST.in规则不生效
  • 使用pyproject.toml配置的项目（setuptools/poetry等工具）：未正确配置packages或include字段，若你的包目录名与项目名不一致，默认打包规则会遗漏非同名目录的源码
• Bitbucket远程仓库缺失源码文件
  检查本地.gitignore规则是否错误忽略了.py文件或你的包目录，可直接登录Bitbucket查看仓库对应目录下是否存在.py文件，若远程仓库本身没有源码，安装后自然为空
• 安装命令拉取的分支错误
  你本地开发的源码可能提交在非默认分支（非main/master分支），pip安装git仓库时默认拉取默认分支，可指定分支验证：

  pip install git+https://my_name@bitbucket.org/my_company/my_repo.git@你的开发分支名
  

快速验证方法 #

在本地项目根目录下执行无软链接的普通安装命令pip install .，如果该安装方式也出现包无法导入、site-packages对应目录无源码的问题，说明是本地打包配置问题，和Bitbucket仓库无关，修正配置后重新推送即可。

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