如何解决pip安装报错ModuleNotFoundError: No module named ‘keras’问题

【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named ‘keras’问题

摘要

在使用 PyCharm 进行深度学习项目开发时，常常需要通过 pip install keras 来安装 Keras 库。但有时即便命令执行成功，运行代码时依旧出现以下异常：

ModuleNotFoundError: No module named ‘keras’

这种问题困扰了不少开发者，尤其是在 macOS 环境下结合 PyCharm 2025 新版本使用虚拟环境时。本文将深入剖析该异常产生的开发场景与技术细节，并提供超详细的解决方案，帮助大家快速定位并彻底修复此类 pip install 问题。

---

一、开发环境

• 操作系统：macOS 13.x（Apple Silicon M1/M2 兼容）
• Python 版本：Python 3.10.x
• IDE：PyCharm 2025.1.2
• 虚拟环境：venv / Conda
• 网络：国内环境，部分场景需配置镜像源

二、问题场景与复现

当在 PyCharm 的 Terminal 或者 Run Configuration 中执行以下命令时：

pip install keras

显示安装成功（或已安装最新版本），但在代码中导入时：

import keras

依然报错：

ModuleNotFoundError: No module named 'keras'

引用：该异常通常源于环境隔离或路径配置不当，排查时要先确认 PyCharm 终端与代码运行所用解释器是否一致。

三、原因分析

1. 模块未真正安装到当前解释器
2. PyCharm 使用的解释器不是预期的虚拟环境
3. 自定义包名与官方包名冲突
4. 环境变量（PYTHONPATH）未包含项目或模块路径
5. 相对导入或 __init__.py 配置错误
6. pip 版本过旧导致安装失败或路径混乱

四、解决方案

1. 检查解释器与包安装路径

which python
which pip
pip show keras

• 确认 pip 对应同一 Python 解释器
• 在 PyCharm 的 Settings → Project → Python Interpreter 中，选择与 Terminal 一致的解释器

2. 切换国内镜像源并升级 pip

pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip install keras -U

3. 确认包名与模块名

有时安装 tensorflow 会包含 keras 子模块，可直接：

pip install tensorflow

或在代码中：

from tensorflow import keras

4. 添加或检查 __init__.py

• 确保自定义模块路径下存在空的 __init__.py 文件，以便 Python 将其识别为包

5. 设置或更新 PYTHONPATH

• 在 macOS 下，可在终端或 PyCharm 环境变量中添加：

export PYTHONPATH="/Users/yourname/project/src:$PYTHONPATH"

6. 避免相对导入误用

• 使用绝对导入：

# 错误
from ..mysubmodule import foo

# 正确
from project.mysubmodule import foo

7. 清理 pip 缓存

pip cache purge
pip install keras

8. 验证包版本兼容性

方案	说明
pip install keras==2.10.0	如果最新版不兼容，尝试回滚到兼容版本
pip install tensorflow	使用 TensorFlow 内置的 Keras 子模块
conda install keras	Conda 环境下一键安装
python -m pip install	避免 PATH 冲突，使用模块方式执行 pip

五、总结

本文通过排查解释器、镜像源、包名冲突、路径配置、缓存清理、相对导入等多种常见场景，详细介绍了如何解决 PyCharm 控制台下 pip install 后仍报 ModuleNotFoundError: No module named ‘keras’ 的问题。希望能够帮助大家快速定位并修复此类环境配置问题。

更多Bug解决方案请查看==>全栈Bug解决方案专栏https://blog.youkuaiyun.com/lyzybbs/category_12988910.html