Python子项目内部导入报错，求无需修改代码的解决方案

问题场景 #

项目结构如下：

│
├── pckg1/
│   └── utils/
│         ├── module11.py
│         └── module12.py
│
├── pckg2/
│   └── utils/
│         ├── module21.py
│         └── module22.py
│
└── main_pckg/
    ├── utils/
    └── main.py

运行main_pckg/main.py时，从pckg1/utils/module11.py、pckg2/utils/module21.py导入方法，但module11.py内部存在如下导入语句：

from utils.module21 import X,Y,Z

运行时触发错误：

No module named `utils/module21` under the current working dir.

常规方案是将导入改为相对路径，但由于大量模块受版本控制无法修改源码，可采用以下解决方案：

可行解决方案 #

1. 动态修改Python模块搜索路径 #

在main_pckg/main.py的最开头添加代码，将项目根目录加入Python的模块搜索路径：

import sys
import os
# 计算项目根目录（main_pckg的父级目录）
root_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
# 将根目录插入到搜索路径最前端，确保优先级
if root_dir not in sys.path:
    sys.path.insert(0, root_dir)

此方法会让Python在项目根目录下查找utils模块，若存在多个同名utils目录，会优先加载sys.path中靠前位置的对应模块，可根据需求调整插入顺序。

2. 通过环境变量PYTHONPATH指定搜索路径 #

无需修改任何代码，在运行main.py前设置PYTHONPATH为项目根目录：

• Linux/macOS 终端：

export PYTHONPATH=/absolute/path/to/project/root
python main_pckg/main.py

• Windows 命令提示符：

set PYTHONPATH=C:\absolute\path\to\project\root
python main_pckg/main.py

• Windows PowerShell：

$env:PYTHONPATH = "C:\absolute\path\to\project\root"
python main_pckg/main.py

3. 切换到项目根目录运行脚本 #

直接将工作目录切换到项目根目录后运行main.py，Python会自动将当前工作目录加入模块搜索路径：

cd /path/to/project/root
python main_pckg/main.py

此方式无需修改代码或配置环境变量，只需确保运行时的工作目录为项目根目录。

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