ModuleNotFoundError: No module named 'xxx'

Python 导入模块失败时抛出，最常见于包未安装或环境不对。

现象

Traceback (most recent call last):
  File "main.py", line 1, in 
    import requests
ModuleNotFoundError: No module named 'requests'

原因

• 目标包尚未安装（最常见）。
• 当前虚拟环境未激活，pip 装到了别的解释器。
• 包名拼写错误，或 PyPI 名与 import 名不一致（如 pip install Pillow 但 import PIL）。
• 项目使用了 src 布局但未以包方式安装/运行。

解决

# 1. 确认当前解释器
which python; python -V

# 2. 激活虚拟环境（如适用）
source venv/bin/activate        # macOS/Linux
.\venv\Scripts\activate          # Windows

# 3. 安装缺失的包
pip install requests

# 4. 仍失败？检查 pip 对应的 python
python -m pip install requests

预防

• 用 requirements.txt / pyproject.toml 锁定依赖，新环境 pip install -r requirements.txt。
• 始终在虚拟环境中开发，避免污染全局。
• CI 中加一步 pip install -r requirements.txt 提前暴露缺失。

← 返回报错速查库