首页/Python/常见报错

Python 常见报错速查

开发中常遇到的 Python 报错信息，快速定位原因和解决方案。

ModuleNotFoundError: No module named 'xxx'

出现场景：运行脚本或导入第三方模块时

原因：模块未安装，或当前 Python 解释器不在正确的虚拟环境中

解决方案：

  1. 确认虚拟环境已激活：which python 应指向 .venv/bin/python
  2. 安装缺少的模块：pip install xxx
  3. 如果是自己的模块：检查 __init__.py 是否存在，包路径是否正确
  4. 用 python -m 运行脚本避免路径问题：python -m mypackage.main
  5. 检查包名和导入名是否不同（如 pip install Pillow 但 import PIL）

预防：始终在虚拟环境中工作，用 requirements.txt 记录所有依赖，新环境用 pip install -r requirements.txt 初始化

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

出现场景：使用 pip install 安装包时

原因：尝试在系统 Python 中安装包但没有管理员权限，或虚拟环境未激活

解决方案：

  1. 激活虚拟环境后再安装：source .venv/bin/activate && pip install xxx
  2. 如果没有虚拟环境，先创建一个：python -m venv .venv
  3. 临时方案（不推荐）：pip install --user xxx 安装到用户目录
  4. 绝对不要用 sudo pip install，会破坏系统 Python

预防：养成习惯：每个项目都创建虚拟环境，永远不在系统 Python 中直接安装包

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. Package A requires B>=2.0, but you have B 1.5 which is incompatible.

出现场景：安装新包时与已有包的依赖版本冲突

原因：两个包要求同一依赖的不同版本，pip 无法同时满足

解决方案：

  1. 查看冲突详情：pip check
  2. 尝试升级冲突的包：pip install --upgrade B
  3. 查看依赖树找到冲突源：pip install pipdeptree && pipdeptree -r -p B
  4. 重建干净环境：删除 .venv，重新创建并只安装需要的包
  5. 使用 uv pip compile 让解析器自动找到兼容版本组合

预防：使用 pip-compile 或 uv pip compile 管理依赖，它会在安装前解析出兼容的版本组合。定期更新依赖避免版本差距过大

SyntaxError: Missing parentheses in call to 'print'

出现场景：运行包含 Python 2 语法的代码，或 Python 版本不匹配

原因：代码使用了 Python 2 的 print 语句语法（print "hello"），但运行环境是 Python 3

解决方案：

  1. 将 print "hello" 改为 print("hello")
  2. 批量修复：使用 2to3 工具：2to3 -w script.py
  3. 如果是第三方库报错：升级到支持 Python 3 的版本
  4. 确认 Python 版本：python --version

预防：确保项目声明了最低 Python 版本要求（pyproject.toml 中的 requires-python），使用 ruff 检查 Python 版本兼容性

RecursionError: maximum recursion depth exceeded

出现场景：递归函数调用层数过深，或对象间循环引用触发无限递归

原因：递归没有正确的终止条件，或数据结构存在循环引用导致无限递归

解决方案：

  1. 检查递归函数的终止条件（base case）是否正确
  2. 用迭代替代递归：将递归改写为 while 循环 + 栈
  3. 如果确实需要深递归：import sys; sys.setrecursionlimit(10000)（谨慎使用）
  4. 检查 __repr__ 或 __str__ 方法是否触发了循环引用
  5. 使用 @functools.lru_cache 缓存递归结果避免重复计算

预防：递归函数始终先写终止条件，对于可能很深的递归（如树遍历）优先考虑迭代实现。Python 默认递归限制 1000 层，不适合深度递归算法