场景还原
假设你的项目目录结构如下（以 Open WebUI 为例）：
/home/openwebui/open-webui/
├── backend/
│ ├── open_webui/
│ │ ├── __init__.py
│ │ ├── main.py
│ │ └── utils/
│ │ ├── __init__.py
│ │ └── cleanup_vector_collections.py
你在 backend 目录下执行如下命令运行某个工具脚本：
cd backend python open_webui/utils/cleanup_vector_collections.py
结果却报错：
ModuleNotFoundError: No module named 'open_webui'
原因解析：sys.path决定了模块能不能被找到
Python 在运行脚本时，会将当前执行脚本的目录加入 sys.path 的第一个位置。这意味着：
python open_webui/utils/xxx.py，当前路径就是 backend/。但是 open_webui 并不在 backend/open_webui 中被 Python 认为是顶级模块，除非 backend/ 被加入到 PYTHONPATH。
解决方案一：设置PYTHONPATH
通过显式指定 Python 的模块搜索路径，来告诉解释器从哪里找模块：
PYTHONPATH=. python open_webui/utils/cleanup_vector_collections.py
解释：
PYTHONPATH=. 表示将当前目录（backend）加入模块搜索路径。这样 from open_webui.env import SRC_LOG_LEVELS 就不会报错了。
解决方案二：使用模块运行方式（推荐）
Python 提供了 -m 参数来以模块方式运行脚本，它可以自动把包结构考虑进去：
python -m open_webui.utils.cleanup_vector_collections
但注意：
你必须在backend/ 目录下运行（即 open_webui 是当前目录下的包）。open_webui/ 和其子目录需要包含 __init__.py 文件，才会被识别为合法包。
最佳实践总结
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| 运行模块脚本 | python -m package.module | 保证包路径清晰、稳定 |
| 临时调试脚本 | PYTHONPATH=. python xxx.py | 不修改代码结构，临时指定路径 |
| 多模块脚本开发 | 用 Makefile 或 scripts/ 封装调用 | 自动带上 PYTHONPATH 和参数 |
项目实践示例
比如你可以建立一个启动脚本 scripts/run_cleanup.sh：
#!/bin/bash cd "$(dirname "$0")/../backend" PYTHONPATH=. python -m open_webui.utils.cleanup_vector_collections
或者添加 .envrc 文件（使用 direnv）自动设置 PYTHONPATH：
export PYTHONPATH=.
常见问题排查清单
有没有漏写 __init__.py 文件？
是否在正确的目录下运行？
是不是直接运行了包内部脚本而没有使用 -m 模式？
是否有名称冲突？（模块名与包名或标准库重复）
结语
模块导入问题看似小事，实则是 Python 项目结构设计和代码组织规范的体现。掌握 PYTHONPATH 和 -m 运行方式，不仅可以解决 ModuleNotFoundError，也能帮助你更好地组织工程、部署项目。
到此这篇关于Python项目报错ModuleNotFoundError的终极解决方案的文章就介绍到这了,更多相关Python报错ModuleNotFoundError内容请搜索以前的文章或继续浏览下面的相关文章希望大家以后多多支持！
