Python多级模块导入失败，咨询基于命名空间的导入处理方案

项目结构 #

│   main.py
│
└───src
    ├───functions
    │       hello.py
    │       
    └───models
            hello_model.py

现有代码 #

main.py #

from src.functions.hello import http_message

if __name__ == "__main__":
    print(http_message("This is a test message").message)

src/functions/hello.py #

from models.hello_model import HttpMessageModel

def http_message(message: str) -> HttpMessageModel:
    return HttpMessageModel(
        message=message,
        code=200,
    )

src/models/hello_model.py #

from dataclasses import dataclass

@dataclass
class HttpMessageModel:
    message: str
    code: int

报错信息 #

执行py main.py时出现错误：

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    from src.functions.hello import http_message
  File "L:\wamp64\www\GITHUB\create-python-app\src\functions\hello.py", line 1, in <module>
    from models.hello_model import HttpMessageModel
ModuleNotFoundError: No module named 'models'

解决方法 #

方法1：使用绝对导入 #

修改src/functions/hello.py中的导入语句，从项目根目录出发指定完整模块路径：

from src.models.hello_model import HttpMessageModel

def http_message(message: str) -> HttpMessageModel:
    return HttpMessageModel(
        message=message,
        code=200,
    )

这种方式明确指定模块的完整命名空间，Python会从main.py所在的项目根目录定位到src.models模块。

方法2：使用相对导入 #

在src/functions/hello.py中通过相对路径导入同级目录下的models模块：

from ..models.hello_model import HttpMessageModel

def http_message(message: str) -> HttpMessageModel:
    return HttpMessageModel(
        message=message,
        code=200,
    )

• ..代表上一级目录（即src目录），以此定位到src/models模块。
• 注意：相对导入仅适用于作为包被导入的模块，直接运行hello.py会报错，但通过main.py导入运行时可正常工作。

方法3：添加项目根目录到Python搜索路径 #

如果不想修改代码，可以临时将项目根目录加入Python的模块搜索路径：

方式A：通过环境变量设置

Windows环境，运行main.py前执行：

set PYTHONPATH=%cd%

Linux/macOS环境，运行前执行：

export PYTHONPATH=$(pwd)

之后再执行py main.py，Python就能在项目根目录下找到models模块。

方式B：在代码中动态添加路径

修改main.py，在导入模块前将项目根目录加入sys.path：

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

from src.functions.hello import http_message

if __name__ == "__main__":
    print(http_message("This is a test message").message)

这种方式会动态扩展Python的模块搜索范围，确保能找到目标模块。

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

把src目录转为Python包，支持全局导入：

1. 在src目录下创建空的__init__.py文件，标记该目录为Python包。
2. 在项目根目录创建pyproject.toml文件，内容如下：

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

[project]
name = "your-project-name"
version = "0.1.0"
packages = ["src"]

3. 执行本地开发安装命令：

pip install -e .

安装完成后，即可在任何位置使用绝对导入语句，Python会自动识别这个包。

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