Python3.9：解决跨文件夹相对导入函数的ImportError报错

问题场景 #

现有文件夹结构：

root_folder/
    utils_folder/
        __init__.py
        helper_functions.py (定义了Function_A)
    module_A_folder/
        Script_A.py (需要调用Function_A)

utils_folder/__init__.py内容：

from .helper_functions import Function_A

在Script_A.py中尝试用from ..utils_folder import Function_A导入时，出现错误：

ImportError: attempted relative import with no known parent package

使用Python 3.9 x64版本。

报错原因 #

直接运行Script_A.py时，Python会将其视为独立的顶级脚本，而非root_folder包的一部分，因此无法识别..这种表示父包的相对路径语法。

解决方法 #

方法1：以包的形式运行脚本 #

1. 在root_folder下创建空的__init__.py文件，将其标记为Python包。
2. 切换到root_folder的父目录，用模块方式运行脚本：

   python -m root_folder.module_A_folder.Script_A
   

3. 此时Script_A.py中可以选择：
   • 继续使用相对导入：

     from ..utils_folder import Function_A
     

   • 改用绝对导入：

     from root_folder.utils_folder import Function_A
     

方法2：手动添加根目录到Python路径 #

在Script_A.py的开头添加代码，将root_folder的路径加入Python的搜索路径：

import sys
from pathlib import Path

# 获取root_folder的绝对路径
root_dir = Path(__file__).resolve().parent.parent
sys.path.append(str(root_dir))

# 直接导入Function_A
from utils_folder import Function_A

之后正常运行Script_A.py即可。

方法3：通过环境变量指定根路径 #

运行脚本前，设置PYTHONPATH环境变量指向root_folder：

• Windows命令行：

  set PYTHONPATH=C:\实际路径\root_folder
  python module_A_folder\Script_A.py
  

• Linux/macOS终端：

  export PYTHONPATH=/实际路径/root_folder
  python module_A_folder/Script_A.py
  

设置后，Script_A.py中直接用from utils_folder import Function_A即可完成导入。

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