解决 VSCode 运行 Python 时 ModuleNotFoundError: No module named ‘open_webui‘ 问题

目录

[1. 问题原因分析](#1. 问题原因分析)

[2. 解决思路](#2. 解决思路)

[3. 解决步骤](#3. 解决步骤)

[3.1 打开或创建 .vscode/launch.json](#3.1 打开或创建 .vscode/launch.json)

[3.2 添加调试配置](#3.2 添加调试配置)

[3.3 配置说明](#3.3 配置说明)

[3.4 运行测试](#3.4 运行测试)

[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 在导入模块时，会从以下位置按顺序查找：

1. 当前运行文件所在目录

2. 环境变量 PYTHONPATH 中指定的目录

3. 标准库路径

4. 已安装的第三方包路径（site-packages）

当你在 VSCode 中直接运行 main.py 时，当前工作目录（cwd）默认为打开的文件所在目录 ，而不是 backend。

这样 open_webui 这个包就找不到了。

---

2. 解决思路

有三种常见方法可以解决这个问题：

1. 调整 VSCode 的工作目录（cwd）

2. 设置 PYTHONPATH 环境变量

3. 在代码中动态修改 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 运行测试

保存配置文件后：

1. 在 VSCode 左侧选择 运行与调试 面板

2. 选择刚才创建的 "Python Debugger: Current File"

3. 点击绿色运行按钮或按 F5

此时程序会正常启动，不再报 ModuleNotFoundError。

---

4. 总结

通过调整 VSCode 的 工作目录（cwd） 和 PYTHONPATH 环境变量 ，我们可以解决大多数 包导入失败 的问题。

优点：

• 不污染全局环境变量

• 不需要修改项目源码

• 对整个项目的调试都有效

适用场景：

• 项目目录不是纯顶层包结构

• 想要在 VSCode 里一键运行而不是手动设置命令行路径

---

💡 小贴士

如果你的项目有多个入口文件，可以在 launch.json 里配置多个 configurations，分别对应不同的启动文件，这样可以随时切换运行目标。