无法跨模块导入自定义函数：ModuleNotFoundError问题排查

你的项目结构 #

calculator_project
│   __init__.py
│
└───calculator_package
    │   LICENSE
    │   pyproject.toml
    │   README.md
    │   setup.cfg
    │   __init__.py
    │
    ├───src
    │   └───og_calculator_package
    │           calculator.py
    │           __init__.py
    │
    └───tests
            tests.py
            __init__.py

问题场景 #

calculator.py中定义了加法函数：

def add(x, y):
    return x + y

在tests.py中尝试导入时使用：

from src.og_calculator_package.calculator import add

抛出错误：

ModuleNotFoundError: No module named 'src'

问题原因 #

Python的模块查找路径（sys.path）中没有包含calculator_package目录，导致无法识别src作为可导入的顶层模块；或者直接运行tests.py时，工作目录不是项目根目录，使得相对路径逻辑失效。

解决办法 #

1. 使用相对导入 #

由于tests和src是同级目录（均位于calculator_package下），可以用相对导入语法：

from ..src.og_calculator_package.calculator import add

注意：使用相对导入时，不能直接以脚本形式运行tests.py（如python tests.py），必须以模块方式运行，比如从calculator_project目录执行：

python -m calculator_package.tests.tests

2. 手动添加Python路径 #

在tests.py开头加入以下代码，将calculator_package目录添加到Python的模块查找路径：

import sys
import os
# 获取当前文件所在目录的上级目录（即calculator_package）
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

from src.og_calculator_package.calculator import add

这样Python就能找到src模块，直接运行tests.py也能正常工作。

3. 安装本地开发包（推荐） #

你的项目包含pyproject.toml和setup.cfg，属于标准的可安装包结构。在calculator_package目录下执行：

pip install -e .

这会以可编辑模式安装本地包，之后你可以直接使用包名导入，无需关心路径：

from og_calculator_package.calculator import add

这种方式符合Python包开发的规范，适合长期维护的项目。

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