从src目录导入包时出现ModuleNotFoundError问题排查

项目结构 #

.
└── src
    ├── __init__.py
    ├── lib
    │   ├── hello.py
    │   └── __init__.py
    ├── libtwo
    │   ├── __init__.py
    │   └── world.py
    └── main.py

相关代码 #

world.py 代码：

def helloworld():
    print("Hello World!")

报错情况 #

• 在main.py中使用from libtwo.world import helloworld可正常运行
• 在hello.py中使用相同语句时，报错：

File "src/lib/hello.py", line 1, in <module>
    from libtwo.world import helloworld
ModuleNotFoundError: No module named 'libtwo'

• 改用相对导入from ..libtwo.world import helloworld，又报错：

File "lib/hello.py", line 1, in <module>
    from ..libtwo.world import helloworld
ImportError: attempted relative import with no known parent package

环境说明 #

使用VSCode，已配置"python.terminal.executeInFileDir": true，处于虚拟环境中。查看sys.path发现：运行main.py时路径包含src目录，但直接运行hello.py时不包含。

解决方案 #

方案1：以模块方式运行hello.py #

切换到项目根目录（src的上级目录），在终端执行：

python -m src.lib.hello

这种运行方式会自动将项目根目录加入sys.path，Python能识别src下的所有子模块，相对导入也可正常工作。

方案2：手动添加src目录到模块搜索路径 #

在hello.py开头添加以下代码，把src目录的绝对路径加入sys.path：

import sys
import os
# 从hello.py所在目录向上两级定位到src目录
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))

from libtwo.world import helloworld

方案3：调整VSCode运行配置 #

修改VSCode的launch.json配置，确保运行hello.py时将src目录加入PYTHONPATH。示例配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: hello.py",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "cwd": "${workspaceFolder}",
            "env": {"PYTHONPATH": "${workspaceFolder}/src"},
            "console": "integratedTerminal"
        }
    ]
}

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