Mac系统下Python跨目录导入文件报No module错误如何解决？

项目目录结构如下：

报错原因 #

Python 导入模块时的默认搜索路径包含：运行脚本的当前工作目录、Python 标准库路径、已安装的第三方库路径。
你单独运行 v3/extensions/settings/main.py 时，当前工作目录为 v3/extensions/settings/，同目录下的 theme 包属于搜索路径范围内，因此不会报错；但运行 v3/extendednb.py 时，当前工作目录切换为 v3/，Python 不会自动递归搜索所有子目录，因此找不到位于 v3/extensions/settings/ 下的 theme 包。

可行解决方案 #

方案1：使用相对导入（推荐，符合Python包规范） #

修改 v3/extensions/settings/main.py 中的导入语句，用相对路径指向同包内的模块：

# 替换原有导入语句
from .theme import main as theme_Main
from . import restart
from .restart import restart_program
from .theme.main import *

如果需要单独运行 v3/extensions/settings/main.py，不要直接执行 python main.py，改为在 v3 目录下执行模块运行命令：

python -m extensions.settings.main

方案2：使用绝对导入（兼顾单独运行和项目启动） #

修改 v3/extensions/settings/main.py 中的导入语句，写全从项目根目录开始的完整导入路径：

# 替换原有导入语句
from extensions.settings.theme import main as theme_Main
from extensions.settings import restart
from extensions.settings.restart import restart_program
from extensions.settings.theme.main import *

如果单独运行 v3/extensions/settings/main.py 时仍报错，可以在该文件最开头加入代码，临时将项目根目录（即 v3 目录）加入搜索路径：

import sys
from pathlib import Path
# 三次parent是从main.py的路径往上跳三级到v3目录：main.py → settings → extensions → v3
sys.path.append(str(Path(__file__).parent.parent.parent.resolve()))

方案3：全局配置环境变量（永久生效，适合本地开发） #

在Mac终端的配置文件（~/.zshrc 或 ~/.bash_profile，取决于你用的shell）中加入以下内容，将项目根目录永久加入Python搜索路径：

export PYTHONPATH="$PYTHONPATH:/你的完整路径/v3"

修改后执行 source ~/.zshrc（或对应配置文件）使配置生效，之后无论从哪个位置启动脚本都不会出现导包错误。

内容的提问来源于stack exchange，提问作者AG-88301