Python包导入报错：no module named 'Package1' 技术求助

问题背景 #

跨包导入时触发ModuleNotFoundError: No module named 'Package1'，项目结构如下：

Project/
├── Package1/
│   ├── __init__.py
│   ├── Module1.py
│   └── Module2.py
└── Package2/
    ├── __init__.py
    ├── Module3.py
    └── Module4.py

相关代码：
Module2.py：

def function1():
    print('this is function1 from module1 in package1')

Module4.py：

from Package1 import Module2

Module2.function1()

可能的原因及解决方法 #

1. 运行脚本的工作目录错误 #

如果直接在Package2目录下执行python Module4.py，Python会将Package2视为当前根路径，无法找到上层的Package1。
解决：切换到Project根目录，通过相对路径运行脚本：

cd /path/to/Project
python Package2/Module4.py

2. Project目录未加入Python搜索路径 #

Python仅在sys.path列表中的目录查找模块，若Project目录不在其中，会导致导入失败。
解决方法：

• 临时添加（调试用）：在Module4.py开头添加代码，将Project目录加入sys.path：

  import sys
  from pathlib import Path
  
  # 获取Project目录的绝对路径
  project_dir = Path(__file__).parent.parent
  sys.path.append(str(project_dir))
  
  from Package1 import Module2
  Module2.function1()
  

• 永久添加：将Project目录路径添加到PYTHONPATH环境变量：
  • Windows命令行：

    set PYTHONPATH=C:\path\to\Project;%PYTHONPATH%
    

  • Linux/macOS终端：

    export PYTHONPATH="/path/to/Project:$PYTHONPATH"
    

  若要永久生效，可将上述命令写入shell配置文件（如~/.bashrc、~/.zshrc）。

3. init.py文件异常 #

若Package1下的__init__.py存在语法错误或异常逻辑，可能导致包无法被识别。
解决：暂时清空__init__.py（保留空文件即可，Python仅需该文件标记目录为包），重新测试导入。

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