根本原因是Python运行时找不到模块，即模块未在sys.path中：常见于环境不匹配（如系统Python与虚拟环境混用）、pip与python解释器路径不一致、包名与导入名不符（如pip install Pillow但需from PIL import Image），解决关键是确保python -m pip install与当前解释器路径一致，并验证pip show和sys.path中的路径是否匹配。

为什么 pip install 了还是报 ModuleNotFoundError

根本原因不是没装，而是 Python 运行时找不到那个模块——它不在 sys.path 列表里。常见于：装到了系统 Python 却用 virtualenv 启动脚本、用 conda 环境却调了系统 pip、或装了但拼错了包名（比如 pip install requests 正确，但代码里写了 import requets）。

先确认当前 Python 解释器路径和 pip 是否匹配：

which python
which pip
python -m pip --version

三者输出的路径必须一致（尤其注意是否混用了 /usr/bin/python3 和 ~/venv/bin/python）。不一致就立刻用对应环境的 pip 安装：

• python -m pip install xxx —— 最稳妥，强制用当前 python 对应的 pip
• 别直接敲 pip install xxx，除非你 100% 确认 shell 的 pip 指向当前解释器
• 虚拟环境中务必激活后再操作：source venv/bin/activate（Linux/macOS）或 venv\Scripts\activate（Windows）

如何快速验证模块是否真在 sys.path 里

不要靠猜，直接进 Python 交互式环境查：

python
>>> import sys
>>> '\n'.join(sys.path)

重点看前三项：当前目录、site-packages 路径、标准库路径。如果模块已安装但不在其中任何一项里，说明它装到了别的环境。

检查模块是否真的被 pip 认为“已安装”：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• pip list | grep xxx（Linux/macOS）或 pip list | findstr xxx（Windows）
• pip show xxx —— 显示详细路径，对比它是否落在 sys.path 中某个 site-packages 下
• 如果 pip show 报错“Package not found”，说明根本没装到当前环境

常见陷阱：包名 ≠ 导入名

这是最隐蔽也最高频的错误。比如：

• pip install python-dotenv → 但代码里要写 import dotenv，不是 import python-dotenv
• pip install Pillow → 导入名是 from PIL import Image，不是 import Pillow
• pip install opencv-python → 导入名是 import cv2

解决方法只有一个：查官方文档首页的 “Installation” 和 “Usage” 小节，或看 PyPI 页面的 “How to use” 示例。别凭名字脑补导入名。

临时加路径不是长久之计，但调试时有用

如果确认模块就在某目录下（比如自己写的 mylib/），又不想现在就装，可以临时加进 sys.path：

import sys
sys.path.insert(0, '/absolute/path/to/mylib')  # 必须是绝对路径
import mymodule

但注意：

• 只对当前进程生效，脚本结束就丢
• 永远用绝对路径，./mylib 在不同工作目录下会失效
• 上线前必须改成 proper install：pip install -e /path/to/mylib（开发模式）

真正难搞的往往不是路径问题，而是你以为自己在用 A 环境，其实 IDE 或终端悄悄切到了 B 环境——多打两遍 which python 和 python -c "import sys; print(sys.executable)" 不费事。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！