Google Colab从谷歌云盘导入自定义私有Python包失败问题排查

可能的原因 #

1. 包结构不规范：本地能运行但Colab无法识别，大概率是包的目录结构不符合Python包规范。比如mypackage目录下缺失__init__.py文件，或是setup.py/pyproject.toml中的包名、模块路径配置错误。
2. Colab多Python环境冲突：Colab默认存在多个Python版本，%pip install可能安装到了当前内核未使用的环境中，导致导入失败。
3. 云盘挂载权限/延迟问题：谷歌云盘挂载后，部分文件权限未同步，或是Colab读取云盘目录时有延迟，导致安装后无法识别模块。
4. 安装未触发正确构建：直接安装本地目录时，若未正确执行setup.py的构建步骤，可能仅创建了目录链接而非真正完成安装，导致模块路径未被Python识别。

分步解决方法 #

1. 检查并修正包结构 #

先确认/content/drive/MyDrive/mypackage/的目录结构是否符合规范：

mypackage/
├── setup.py  # 或 pyproject.toml
├── mypackage/
│   ├── __init__.py
│   ├── 你的模块文件.py
│   └── ...
└── ...

• 必须存在与包名一致的内层mypackage目录，且目录内要有__init__.py（空文件也可）。
• 检查setup.py中的packages参数，确保包含目标包：

  from setuptools import setup, find_packages
  
  setup(
      name="mypackage",
      version="0.1.0",  # 必须指定版本，否则pip freeze会显示无版本信息
      packages=find_packages(),
      # 其他依赖等配置
  )
  

2. 确保安装到当前内核的Python环境 #

在Colab中执行以下命令，强制使用当前内核对应的pip安装包，避免环境冲突：

import sys
print(sys.executable)
!{sys.executable} -m pip install /content/drive/MyDrive/mypackage/

3. 重新安装并清理缓存 #

先卸载已安装的包，再重新安装并强制清理缓存，避免旧配置干扰：

!pip uninstall -y mypackage
!pip install --force-reinstall --no-cache-dir /content/drive/MyDrive/mypackage/

4. 验证安装路径并手动添加（若必要） #

安装完成后，查看包的实际安装位置：

!pip show mypackage

将输出中的Location路径添加到sys.path后再尝试导入：

import sys
sys.path.append("/path/to/mypackage/location")  # 替换为实际的Location路径
import mypackage

5. 用极简测试包验证环境 #

如果以上步骤无效，可创建一个极简测试包验证Colab环境是否正常：
在云盘新建test_package目录，结构如下：

test_package/
├── setup.py
└── test_package/
    ├── __init__.py
    └── hello.py

setup.py内容：

from setuptools import setup, find_packages

setup(
    name="test_package",
    version="0.1.0",
    packages=find_packages()
)

hello.py内容：

def say_hello():
    print("Hello from test package!")

执行安装和导入测试：

!pip install /content/drive/MyDrive/test_package/

from test_package.hello import say_hello
say_hello()

如果测试包能正常运行，说明原包结构存在问题，需对照测试包修正。

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