为何Python误将文件夹识别为模块？项目内部导入问题求解

问题原因 #

直接运行folder1/script时，Python会将script所在的folder1目录加入模块搜索路径sys.path，而非project的父目录。此时Python无法找到project包，因为它不在搜索路径范围内。而在项目外导入script时，project的父目录已经处于sys.path中（当前工作目录为该父目录），所以导入逻辑正常。

解决方案 #

1. 动态添加项目路径到sys.path #

在script开头添加代码，手动将project目录加入Python的模块搜索路径：

import sys
from pathlib import Path

# 获取project目录的绝对路径（folder1的父目录即为project）
project_root = Path(__file__).parent.parent
sys.path.append(str(project_root))

# 现在可以正常执行导入
from project.folder2 import some_file as file

2. 使用相对导入+模块模式运行 #

由于script属于project包的子模块，可使用相对导入语法：

from ..folder2 import some_file as file

但直接运行script会触发ValueError: attempted relative import in non-package，需在project的父目录下，用-m参数以模块方式运行脚本：

python -m project.folder1.script

这种方式会让Python将project识别为合法包，相对导入可正常工作。

3. 设置PYTHONPATH环境变量 #

运行脚本前，将project的父目录添加到PYTHONPATH环境变量中：

• Linux/macOS终端：

  export PYTHONPATH="/path/to/project_parent_dir:$PYTHONPATH"
  python /path/to/project/folder1/script
  

• Windows命令行：

  set PYTHONPATH=C:\path\to\project_parent_dir;%PYTHONPATH%
  python C:\path\to\project\folder1\script
  

Python启动时会自动加载该路径，无需修改代码即可找到project包。

导入folder_3内容的方法 #

解决project包的搜索路径问题后，导入folder_3的方式与导入some_file一致，无需特殊处理：

• 绝对导入（适用于所有解决方案）：

  # 导入folder_3中的某个模块
  from project.folder2.folder_3 import target_module
  # 或直接导入模块内的对象
  from project.folder2.folder_3.target_module import some_class
  

• 相对导入（仅适用于模块模式运行）：

  from ..folder2.folder_3 import target_module
  

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