Python报ModuleNotFoundError或ImportError的本质是解释器找不到模块，主因是未安装或不在sys.path中；需确认Python与pip环境一致、检查sys.path并合理管理虚拟环境。
运行 Python 脚本时报 ModuleNotFoundError 或 ImportError，本质是 Python 解释器在当前环境里找不到你要导入的模块。核心原因就两个：模块没装，或者装了但不在 Python 的搜索路径（sys.path）里。
确认模块是否已安装
在命令行中执行：
pip list | grep 模块名 # Linux/macOS pip list | findstr 模块名 # Windows
或者更直接地测试导入：
python -c "import requests; print(requests.__version__)"
如果报错，说明确实没装。用 pip install 模块名 安装即可。注意：确保你用的是和运行脚本**同一个 Python 环境**的 pip（比如用了 python3.9 -m pip install，就别用系统默认的 pip）。
立即学习“Python免费学习笔记（深入）”；
Handsfree Windows Control
下载
通过 handsfree-windows CLI控制 Windows 本机应用 (UIA) 和浏览器 (Playwright) 的引导技能，用于自动化或测试桌面应用。
检查 Python 解释器和 pip 是否匹配
常见陷阱：你用 python script.py 运行，但 pip install 装到了另一个 Python 版本下。验证方法：
- 查当前 Python 路径：
python -c "import sys; print(sys.executable)" - 查当前 pip 对应的 Python：
pip -V（会显示“from xxx/pythonxx/site-packages”） - 强制用当前 Python 调用 pip：
python -m pip install 模块名
检查模块是否在 sys.path 中
Python 只在 sys.path 列出的目录里找模块。临时查看：
python -c "import sys; print('\n'.join(sys.path))"
如果你的模块在某个自定义路径（比如项目里的 lib/），但该路径不在 sys.path 中，有几种办法：
- 运行时加路径：
python -c "import sys; sys.path.insert(0, '/path/to/your/module'); import mymodule" - 设环境变量：
PYTHONPATH=/path/to/your/module python script.py - 在脚本开头加（不推荐长期用）：
import sys; sys.path.append('/path/to/your/module')
虚拟环境问题（高频原因）
如果你在虚拟环境中开发，但忘了激活，或用错了环境，就会“明明装了却找不到”。确认方式：
- 看命令行提示符是否含虚拟环境名（如
(venv)） - 运行
which python（macOS/Linux）或where python（Windows），路径是否指向虚拟环境目录 - 进虚拟环境再装：
source venv/bin/activate（Linux/macOS）或venv\Scripts\activate（Windows）
基本上就这些。重点盯住“用的是哪个 Python”、“pip 装到哪儿去了”、“模块路径在不在 sys.path 里”这三点，90% 的问题都能快速定位。
