如何解决Python包相对导入与直接运行模块的冲突问题

问题根源 #

Python对模块的两种运行场景处理逻辑不同：

• 当模块作为包的一部分被导入（比如example1.py导入它），相对导入from .file1_1 import *能正常识别父包上下文；
• 当直接运行模块（比如python file1.py），它会被当作顶层脚本，没有父包关联，导致相对导入报错；
• 改用绝对导入from file1_1 import *时，直接运行脚本能找到同目录的file1_1，但作为包导入时，Python会从sys.path的顶层路径查找，找不到file1_1模块。

解决方法 #

方法1：遵循包规范运行模块

从main_folder的上级目录，使用模块方式运行file1.py：

python -m main_folder.folder1.file1

这种方式会让Python将main_folder识别为包，相对导入能正常工作，同时example1.py的运行不受影响（确保example1.py中用from main_folder.folder1 import file1这类包路径导入）。

方法2：添加兼容逻辑适配两种场景

在file1.py中加入判断，根据运行场景切换导入方式：

if __name__ == "__main__":
    # 直接运行时，把当前脚本所在目录加入系统路径
    import sys
    from pathlib import Path
    sys.path.append(str(Path(__file__).parent))
    from file1_1 import *
else:
    # 作为包的一部分被导入时，使用相对导入
    from .file1_1 import *

这样不管是直接运行file1.py，还是通过example1.py导入，都能正常执行。

方法3：使用基于包的绝对导入

将file1.py中的导入改为包路径的绝对导入：

from main_folder.folder1.file1_1 import *

同时确保main_folder的上级目录在Python的sys.path中：

• 运行example1.py时，因为它和main_folder同级，默认会将自身所在目录加入sys.path，所以能正常识别；
• 直接运行file1.py时，需要在脚本开头添加路径配置：

import sys
from pathlib import Path
# 将main_folder的上级目录加入sys.path
sys.path.append(str(Path(__file__).parent.parent.parent))
from main_folder.folder1.file1_1 import *

这种方式更符合大型项目的包结构规范，但需要手动维护路径。

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