在pg_util模块目录内执行绝对导入from pg_util.pg_util import失败的问题咨询

问题复现 #

你已通过pip install -e .将pg_util作为可编辑包安装，在项目根目录或非模块子目录的位置，绝对导入可以正常工作：

(py3) sir@cork:~$ python -c "from pg_util.pg_util import DatabaseParams"

但进入模块子目录~/software/fingerWriterAI/pg_util/pg_util后，执行相同导入会触发报错：

(py3) sir@cork:~/software/fingerWriterAI/pg_util/pg_util$ python -c "from pg_util.pg_util import DatabaseParams"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'pg_util.pg_util'; 'pg_util' is not a package

原因分析 #

这个问题的核心是Python模块搜索路径的优先级规则和同名文件/包的冲突：

1. 当你进入pg_util/pg_util目录后，Python会自动将**当前工作目录（.）**添加到sys.path的最前端，优先级高于你通过pip install -e安装的包路径；
2. 该目录下恰好存在pg_util.py文件，当你执行from pg_util.pg_util import...时，Python会优先在当前目录查找pg_util——它会把这个.py文件识别为pg_util模块，而非你期望的顶层pg_util包；
3. 单个.py文件是独立模块，不能作为子包的父级容器，因此Python会报错说pg_util不是包，自然找不到pg_util.pg_util。

简单来说：你写的是绝对导入，但Python因为当前目录的优先级更高，先找到了同名的.py文件，而非你安装的顶层包，导致导入逻辑混乱。

解决方案 #

针对你既不想每次切换工作目录、又不想修改文件名的需求，可参考以下几种处理方式：

1. 推荐：规范工作目录

最稳妥的实践是回到项目根目录（~/software/fingerWriterAI/pg_util）再执行代码，此时Python会优先识别你安装的顶层pg_util包，导入逻辑会恢复正常。

2. 临时方案：手动调整sys.path

如果必须在子目录运行代码，可以手动将项目根目录加入sys.path末尾（避免覆盖顶层包的优先级），示例代码如下：

import sys
from pathlib import Path

# 获取项目根目录（当前目录的上一级）
project_root = str(Path(__file__).parent.parent)
# 将根目录加入搜索路径，让Python能找到顶层pg_util包
sys.path.append(project_root)

from pg_util.pg_util import DatabaseParams

注意：此方式仅适合临时场景，长期使用会增加代码维护成本。

3. 彻底方案：重命名避免冲突

最干净的解决方式是把pg_util/pg_util/pg_util.py重命名为更具体的名称（比如database_params.py），导入语句调整为from pg_util.database_params import DatabaseParams，从根源上避免包名与文件名的冲突。

4. 包内模块用相对导入（仅适用于包内部）

如果是在pg_util/pg_util目录下的包模块（而非直接运行的顶层脚本）中导入，可以使用相对导入语法：

from .pg_util import DatabaseParams

注意：相对导入仅能在作为包一部分的模块中使用，不能在直接执行的脚本里生效。

备注：内容来源于stack exchange，提问作者user48956