Python项目跨子文件夹导入模块报错，求解决方案

问题背景 #

项目结构：

project_folder/
    __init__.py
    subfolder/
        __init__.py
        main.py
        generate_values.py
    lib/
        __init__.py
        external.py

运行subfolder/main.py时，generate_values.py无法导入lib/external.py中的calculate_external函数，尝试多种导入方式均报错：

• from lib.external import calculate_external → ModuleNotFoundError: No module named 'lib'
• from project_folder.lib.external import calculate_external → ModuleNotFoundError: No module named 'project_folder'
• from ..lib.external import calculate_external → ImportError: attempted relative import with no known parent package

要求保留subfolder结构，后续多个子文件夹共享lib目录。

解决方案 #

方法1：临时将项目根目录加入Python路径 #

在generate_values.py开头添加代码，把project_folder的绝对路径加入Python模块搜索路径：

import sys
from pathlib import Path

# 获取project_folder的绝对路径
project_root = Path(__file__).parent.parent
sys.path.append(str(project_root))

# 正常导入目标函数
from lib.external import calculate_external

无需修改环境变量，适合快速调试场景。

方法2：设置PYTHONPATH环境变量 #

运行脚本前，将project_folder的绝对路径添加到PYTHONPATH：

• Linux/macOS终端：

  export PYTHONPATH="/absolute/path/to/project_folder"
  python project_folder/subfolder/main.py
  

• Windows命令提示符：

  set PYTHONPATH=C:\absolute\path\to\project_folder
  python project_folder\subfolder\main.py
  

设置后，generate_values.py中直接使用from lib.external import calculate_external即可正常导入。

方法3：以模块方式运行脚本 #

不要直接执行main.py，从project_folder的父目录，用python -m命令以模块形式启动：

cd /path/to/parent_of_project_folder
python -m project_folder.subfolder.main

此时可在generate_values.py中使用相对导入：

from ..lib.external import calculate_external

或绝对导入：

from project_folder.lib.external import calculate_external

符合Python模块规范，适合长期维护的项目。

方法4：将项目打包为可安装包（推荐长期项目） #

在project_folder下创建pyproject.toml文件，示例内容：

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

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

终端中进入project_folder目录，安装为可编辑模式：

pip install -e .

安装完成后，任何位置都可使用绝对导入：

from project_folder.lib.external import calculate_external

适配多子文件夹共享lib的扩展需求。

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