Python ModuleNotFoundError — 解释器或依赖错误

确认实际运行代码的解释器、依赖所在的虚拟环境，以及安装名与导入名是否不同，从而解决模块找不到的问题。

症状

即使 pip install 成功，仍报 ModuleNotFoundError: No module named 'requests'；代码在 IDE 中能运行，但在终端、CI 或 cron 中失败；requirements.txt 中列出的依赖仍然无法导入。

诊断

python -c "import sys; print(sys.executable); print('\n'.join(sys.path))"
python -m pip show requests
python -c "import requests; print(requests.__version__)"

将 sys.executable 与安装依赖时使用的解释器比较。系统 Python 与虚拟环境的 site-packages 不同。如果 pip show 能找到包但导入失败，可能是解释器不一致或包名/导入名不同。直接在失败的解释器下复现导入，可先排除应用代码因素。

根因

失败的 Python 解释器无法在 sys.path 中找到模块。常见原因包括虚拟环境不一致、依赖未安装、发行包名与导入名不同（如 beautifulsoup4 导入为 bs4），或本地同名文件遮蔽了已安装包。

修复

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt
python -m pytest

始终使用 python -m pip，确保 pip 绑定到将要运行代码的解释器。CI 中声明 Python 版本，并在运行测试的同一环境安装依赖。检查官方文档确认导入名；本地 requests.py 之类的文件会遮蔽同名包，应重命名。

验证

sys.executable 指向预期环境。
pip show <package> 与 python -c "import <module>" 使用同一解释器。
在干净虚拟环境中安装并运行测试通过。
同一命令在 CI 和本地都能工作。

不要用全局安装或 sudo 让错误消失，也不要随意修改 PYTHONPATH；应修复环境隔离。