如何解决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 问题。

文章目录

• [【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named 'keras'问题](#【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named ‘keras’问题)
• • 摘要
  • 一、开发环境
  • 二、问题场景与复现
  • 三、原因分析
  • 四、解决方案
  • • [1. 检查解释器与包安装路径](#1. 检查解释器与包安装路径)
    • [2. 切换国内镜像源并升级 pip](#2. 切换国内镜像源并升级 pip)
    • [3. 确认包名与模块名](#3. 确认包名与模块名)
    • [4. 添加或检查 `init.py`](#4. 添加或检查 __init__.py)
    • [5. 设置或更新 PYTHONPATH](#5. 设置或更新 PYTHONPATH)
    • [6. 避免相对导入误用](#6. 避免相对导入误用)
    • [7. 清理 pip 缓存](#7. 清理 pip 缓存)
    • [8. 验证包版本兼容性](#8. 验证包版本兼容性)
  • 五、总结

---

一、开发环境

• 操作系统：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'

安装成功 运行 pip install keras 检查环境 IDE 终端与运行环境不一致 包名冲突或路径错误 切换解释器至虚拟环境 修改 PYTHONPATH 或更正包名

引用：该异常通常源于环境隔离或路径配置不当，排查时要先确认 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.csdn.net/lyzybbs/category_12988910.html