解决 VSCode 运行 Python 时 ModuleNotFoundError: No module named ‘open_webui‘ 问题
目录
1. 问题原因分析
2. 解决思路
3. 解决步骤
3.1 打开或创建 .vscode/launch.json
3.2 添加调试配置
3.3 配置说明
3.4 运行测试
4. 总结
在使用 VSCode 调试 Python 项目时，我们经常会遇到类似下面的错误：
Exception has occurred: ModuleNotFoundError
No module named 'open_webui'File "D:\extracodes\open-webui\backend\open_webui\main.py", line 51, in <module>from open_webui.utils import logger
ModuleNotFoundError: No module named 'open_webui'
这类问题的本质是 Python 模块搜索路径（sys.path）中没有包含你的项目源码目录。
如果项目目录结构不是纯顶层包（例如 backend/open_webui），直接运行会找不到模块。
1. 问题原因分析
Python 在导入模块时，会从以下位置按顺序查找：
-
当前运行文件所在目录
-
环境变量
PYTHONPATH中指定的目录 -
标准库路径
-
已安装的第三方包路径（
site-packages）
当你在 VSCode 中直接运行 main.py 时，当前工作目录（cwd）默认为打开的文件所在目录，而不是 backend。
这样 open_webui 这个包就找不到了。
2. 解决思路
有三种常见方法可以解决这个问题：
-
调整 VSCode 的工作目录（
cwd） -
设置
PYTHONPATH环境变量 -
在代码中动态修改
sys.path（临时方案）
本次采用的是 方法 1 + 方法 2 结合，通过 VSCode launch.json 配置，一劳永逸。
3. 解决步骤
3.1 打开或创建 .vscode/launch.json
在 VSCode 项目根目录下创建 .vscode 文件夹，并新建 launch.json 文件。
3.2 添加调试配置
将以下配置粘贴进去，并根据实际情况修改 program 路径：
{"configurations": [{"name": "Python Debugger: Current File","type": "debugpy","request": "launch","console": "integratedTerminal",// 要运行的 Python 文件路径"program": "${workspaceFolder}/backend/open_webui/main.py",// 设置工作目录为 backend（很关键）"cwd": "${workspaceFolder}/backend",// 设置 PYTHONPATH，让 Python 能找到 open_webui 包"env": {"PYTHONPATH": "${workspaceFolder}/backend"}}]
}
3.3 配置说明
-
"program"：你要运行的 Python 主入口文件 -
"cwd"：调试运行时的工作目录（当前工作路径），这里必须指向backend -
"env"：额外设置环境变量，这里将PYTHONPATH指向backend，让 Python 知道去这个目录找包 -
"console": "integratedTerminal"：让输出显示在 VSCode 内置终端中
3.4 运行测试
保存配置文件后：
-
在 VSCode 左侧选择 运行与调试 面板
-
选择刚才创建的
"Python Debugger: Current File" -
点击绿色运行按钮或按 F5
此时程序会正常启动，不再报 ModuleNotFoundError。
4. 总结
通过调整 VSCode 的 工作目录（cwd） 和 PYTHONPATH 环境变量，我们可以解决大多数 包导入失败 的问题。
优点：
-
不污染全局环境变量
-
不需要修改项目源码
-
对整个项目的调试都有效
适用场景：
-
项目目录不是纯顶层包结构
-
想要在 VSCode 里一键运行而不是手动设置命令行路径
💡 小贴士
如果你的项目有多个入口文件，可以在 launch.json 里配置多个 configurations，分别对应不同的启动文件，这样可以随时切换运行目标。