Python项目同名模块导入冲突：如何导入根目录constants.py？

问题背景 #

你的项目结构如下：

project_root
 ├── foo
 │    ├── __init__.py 
 │    ├── main.py 
 │    └── constants.py
 ├── utils
 │    └── util.py
 └── constants.py

在utils/util.py中尝试通过from constants import SOME_CONSTANT导入根目录的constants.py，但执行foo/main.py时，Python却导入了foo/constants.py，不符合预期。你希望保留foo/constants.py，同时不修改sys.path来解决这个问题。

可行解决方案 #

1. 使用绝对导入（推荐） #

Python 3默认支持绝对导入，只要把项目当作包来运行，就能直接从根目录指定模块导入：

# utils/util.py
from project_root.constants import SOME_CONSTANT

关键前提：从项目根目录执行脚本，并且用-m参数以模块方式启动：

cd project_root
python -m foo.main

这种方式会让Python自动将项目根目录加入模块搜索路径的优先位置，此时绝对导入会优先匹配根目录的constants.py，不会被foo下的同名文件干扰。

2. 使用相对导入 #

如果utils是项目根目录下的子包，可以用相对导入语法从父级目录导入模块：

# utils/util.py
from ..constants import SOME_CONSTANT

注意事项：这种方式要求util.py必须作为模块被导入，不能直接运行utils/util.py脚本（直接运行会触发ValueError: attempted relative import in non-package错误），只有当它被其他模块（比如foo/main.py）导入时，相对导入才能正常工作。

3. 明确区分模块命名（最佳实践） #

从长远维护角度看，避免同名模块是最省心的方案。可以给foo下的constants.py重命名，比如改成foo/foo_constants.py，这样导入时就不会有歧义：

# utils/util.py
from constants import SOME_CONSTANT  # 此时只会匹配根目录的constants.py
# 如果需要导入foo下的常量，直接写：
from foo.foo_constants import SOME_FOO_CONSTANT

方案对比 #

• 若必须保留foo/constants.py，绝对导入+模块方式运行是最稳妥的选择，不需要修改现有文件结构，也符合Python模块规范。
• 相对导入适合小型项目，但限制较多（不能直接运行子模块脚本）。
• 你原有删除foo/constants.py的方案虽然简单，但如果该文件有实际用途，显然不如上述方法灵活。

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