先验证是否“装错地方”，再排查路径、命名等细节问题；重点检查which python与which pip路径是否一致、sys.path是否包含模块路径、部署时解释器是否指向虚拟环境、以及大小写和命名冲突。
确认模块是否真的安装在当前Python环境里
报 ModuleNotFoundError: No module named 'xxx'，第一反应别急着重装，先验证是不是“装错地方”了。很多问题出在 pip 和 python 不是一对——比如你用系统 python3 运行脚本，却用 pip（其实是 pip3 指向另一个环境）装的包。
执行这两条命令，看路径是否一致：
which python which pip
如果不一致，大概率就是环境错乱。解决方法只有两个：
- 统一用虚拟环境：进入项目目录，
python -m venv venv创建，再source venv/bin/activate（Linux/macOS）或venv\Scripts\activate（Windows） - 强制用同一个解释器装包：比如
python -m pip install requests，确保包装进python对应的site-packages
检查 sys.path 是否包含你的模块所在路径
Python 只在 sys.path 列表里的路径中找模块。如果你导入的是自己写的 myutils，而它放在 /home/user/project/libs/myutils/，但这个路径没进 sys.path，就会报错。
立即学习“Python免费学习笔记（深入）”；
运行这段代码看看当前搜索路径：
import sys
print('\n'.join(sys.path))
常见漏掉的路径包括：
- 项目根目录（尤其 WSGI 或宝塔部署时，工作目录不是你想象的那个）
- 自定义模块所在的父级目录（比如
myproject/utils/下的模块，需把myproject加入sys.path） -
venv/lib/python3.x/site-packages被意外清空或权限异常
临时加路径可以写：sys.path.insert(0, '/www/wwwroot/myapp')，但上线前建议改用 pip install -e . 做可编辑安装，一劳永逸。
排查宝塔、WSGI、Docker 等部署场景下的路径与解释器错配
在宝塔 Python 项目管理器里启动失败，日志出现 ModuleNotFoundError，90% 是因为配置项“Python版本”没指向虚拟环境内的解释器，比如填了 /usr/bin/python3 而不是 /www/wwwroot/myapp/venv/bin/python。
检查和修复步骤：
- 进宝塔 → 网站 → Python 项目 → 设置 → “Python版本”下拉菜单选“其他”，手动填入
venv/bin/python的绝对路径 - 在宝塔终端里
cd /www/wwwroot/myapp，然后source venv/bin/activate && pip list，确认flask、django等都在列表里 - 检查
wsgi.py文件开头是否有sys.path.insert(0, '/www/wwwroot/myapp')，否则相对导入会失效
注意：宝塔不会自动帮你激活虚拟环境，所有路径、解释器、依赖都得手动对齐，少一个环节就挂。
别忽略大小写、拼写、__init__.py 和命名冲突
看起来最傻的问题，其实最常发生：
-
import Pandas→ 报错，正确是import pandas（全小写） -
import my_config，但文件叫myconfig.py，或者目录下缺__init__.py，导致 Python 不认这是个包 - 自己写了
requests.py，结果import requests导入的是本地文件，而不是第三方库——名字撞了，优先加载当前目录
这类问题没法靠重装解决，只能逐行核对 import 语句、文件名、目录结构。建议在 IDE 里打开“跳转到定义”功能，点一下 import 就知道它到底导入了谁。
真正麻烦的从来不是“没装包”，而是你以为装了、以为路径对了、以为名字没错——结果三者全偏了一点点。调试时盯着 which python、pip list、print(sys.path) 这三行输出，比反复 pip install 有用十倍。
