子包内无法导入同包中模块的问题求助

为什么会报错？ #

当你直接执行python3 subfolder/script.py时，Python会把subfolder目录加入到模块搜索路径sys.path里，此时script.py被当作顶层独立脚本，而非folder包的一部分。相对导入（比如..）依赖于当前模块所在的包结构，没有父包的情况下自然会抛出ImportError。

可行的解决方法 #

方法1：用模块方式运行（推荐） #

切换到folder的上级目录（比如你现在在folder目录里，先执行cd ..退出去），然后用-m参数以包模块的方式运行脚本：

python3 -m folder.subfolder.script

这时候Python会把folder识别为一个合法的包，script.py里的相对导入from ..module import my_function就能正常工作。

方法2：临时修改模块搜索路径（应急用） #

在script.py的最开头添加代码，手动把folder目录加入到sys.path：

import sys
from pathlib import Path

# 获取当前脚本所在目录的父目录（也就是folder目录）
folder_path = Path(__file__).parent.parent
sys.path.append(str(folder_path))

# 现在可以直接导入目标函数
from module import my_function

这种方法不需要改变运行方式，但缺点是破坏了包的结构逻辑，项目复杂时容易出现导入冲突。

方法3：把项目安装为可编辑包（长期项目推荐） #

在folder目录下创建pyproject.toml文件，内容如下：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "folder"
version = "0.1.0"

然后切换到folder的上级目录，执行以下命令将项目安装为可编辑模式：

pip install -e .

之后不管你在哪个目录运行script.py，都可以直接用绝对导入：

from folder.module import my_function

这种方式最适合长期维护的项目，能完美解决包导入的各种问题。

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