Python特定目录结构下非sys.path方式的相对导入解决方案

目录结构 #

project
├── scripts
│   └── folder
│       └── file.py
└── submodules
    └── lab_devices
        └── optical_devices
            ├── __init__.py
            └── powermeter_driver.py

问题描述 #

在file.py中尝试导入powermeter_driver.py里的PowermeterDriver：

from submodules.lab_devices.optical_devices.powermeter_driver import PowermeterDriver

运行时触发错误：ModuleNotFoundError: No module named 'submodules'，且不想通过sys.path.insert修改路径来解决，求简便方案。

可行解决办法 #

1. 以项目根目录为工作目录运行脚本 #

直接切换到project根目录，再执行脚本：

cd /path/to/project
python scripts/folder/file.py

Python会自动将当前工作目录加入模块搜索路径，submodules作为根目录下的子模块就能被识别，原导入语句无需修改即可正常运行。

2. 将submodules层级转为可导入包 #

在submodules和lab_devices目录下分别添加空的__init__.py文件（optical_devices已有该文件），更新后的目录结构：

project
├── scripts
│   └── folder
│       └── file.py
└── submodules
    ├── __init__.py
    └── lab_devices
        ├── __init__.py
        └── optical_devices
            ├── __init__.py
            └── powermeter_driver.py

之后保持运行时工作目录为project根目录，原导入语句就能正常生效。

3. 使用相对导入（需以包形式运行） #

修改file.py中的导入语句为相对导入，从当前目录向上回溯到项目根目录：

from ...submodules.lab_devices.optical_devices.powermeter_driver import PowermeterDriver

注意：

• 必须为scripts和folder目录添加空的__init__.py，让scripts.folder成为可导入包；
• 运行时必须以包模块的方式执行，不能直接运行脚本文件：

cd /path/to/project
python -m scripts.folder.file

4. 设置PYTHONPATH环境变量 #

将项目根目录添加到PYTHONPATH，让Python自动搜索该路径下的模块：

Linux/macOS

export PYTHONPATH="/path/to/project:$PYTHONPATH"
python scripts/folder/file.py

Windows（命令提示符）

set PYTHONPATH=C:\path\to\project;%PYTHONPATH%
python scripts\folder\file.py

Windows（PowerShell）

$env:PYTHONPATH = "C:\path\to\project;" + $env:PYTHONPATH
python scripts\folder\file.py

设置后原导入语句无需修改，可直接运行脚本。

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