Python 相对路径导入报错 ValueError 的两种解决方案

江屿

发布时间：2026-10-13 | 5人浏览过

原创

本文介绍 Python 中相对路径导入时遇到的 ValueError: Attempted relative import in non-package 错误。提供两种解决方案：一是通过 sys.path 添加父目录路径，二是使用 python -m 以 package 模式执行脚本。结合 __name__ 判断可兼容两种运行方式，确保模块正确加载。

假设项目目录结构如下：

pkg/
 __init__.py
 libs/
 some_lib.py
 __init__.py
 components/
 code.py
 __init__.py

若需在 code.py 中调用 libs/some_lib.py 模块，尝试使用相对导入：from ..libs.some_lib import something，仅添加 __init__.py 仍会触发 ValueError: Attempted relative import in non-package。

可通过以下两种方法解决：

将当前路径加入 sys.path

由于 compontent 和 libs 处于同级目录，可在 code.py 中通过以下代码将父目录加入系统路径：

import sys
from os import path
sys.path.append( path.dirname( path.dirname( path.abspath(__file__) ) ) )

或者采用更通用的方式，直接指定目标文件夹的绝对路径：

import os, sys
lib_path = os.path.abspath(os.path.join('..'))
sys.path.append(lib_path)

随后即可使用 from libs.some_lib import something 进行导入。

以 package 模式执行代码：

python -m pkg.components.code

此时可直接使用 from ..libs.some_lib import something 进行相对导入。

注意，此处无需在文件名后添加 .py 后缀。

总结

可结合上述两种方法，实现兼容不同运行环境的导入逻辑：

if __name__ == '__main__':
 if __package__ is None:
  import sys
  from os import path
  sys.path.append( <path to the package> )
  from libs.some_lib import something
 else:
  from ..libs.some_lib import something

以上为 Python 相对路径导入的完整解决方案，供参考。