如何解决pip安装报错ModuleNotFoundError: No module named ‘notebook’问题
【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named ‘notebook’问题
一、摘要
在使用 PyCharm 进行 Python 开发时，常常需要通过 pip install 安装第三方包。但有时即便已经安装成功，运行代码或在控制台中依然会报出如下错误：
ModuleNotFoundError: No module named ‘notebook’
本文将从开发场景、技术细节入手，深入剖析该异常出现的原因，并提供覆盖各种可能性的多种解决方案，帮助大家快速定位并修复此类 pip install 相关问题。
文章目录
- 一、摘要
- 二、开发环境
- 三、问题重现
- 四、解决方案
- （一）确认解释器一致性
- （二）升级 pip 并切换国内源
- （三）检查模块名与包名
- （四）添加 `__init__.py` 或调整导入方式
- （五）设置或更新 PYTHONPATH
- （六）避免同名冲突
- （七）使用虚拟环境（强烈推荐）
- （八）高级排查流程（Mermaid 流程图示例）
- 五、总结对照表
二、开发环境
- 操作系统：macOS（任意新版均适用）
- Python 版本：3.8 / 3.9 / 3.10 / 3.11
- IDE：PyCharm 2025
- pip 版本：如非最新版建议升级至最新
三、问题重现
在 PyCharm 的 Terminal 或者 Run Console 中执行：
pip install notebook
python -c "import notebook"
即使提示安装成功，却抛出：
ModuleNotFoundError: No module named 'notebook'
出现该问题通常是因为 IDE 和系统终端使用了不同的 Python 解释器或环境，或者包安装过程出现了路径、权限、网络等异常。
四、解决方案
（一）确认解释器一致性
-
打开 PyCharm 设置：
Preferences->Project: xxx->Python Interpreter- 确认当前 Project 使用的解释器与你在终端
which python/which pip指向的保持一致。
-
如果不一致，可添加或切换至正确的环境。
（二）升级 pip 并切换国内源
pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
网络不稳定或访问受限时，切换到国内镜像可以大幅提升安装成功率。
（三）检查模块名与包名
有时包名与模块名并不完全相同，如
opencv-pythonvscv2。
- 确保在
pip install <package>中使用的是正确的包名。 - 在代码中使用
import <module>时请检查拼写是否与实际模块名一致。
（四）添加 __init__.py 或调整导入方式
-
对于自建 package，确保每个子目录下都有空的
__init__.py文件，以便被识别为模块。 -
若使用相对导入遇到问题，尝试改为绝对导入：
from mypackage.module import MyClass
（五）设置或更新 PYTHONPATH
-
在终端或 IDE 中设置环境变量：
export PYTHONPATH="$PYTHONPATH:/path/to/your/module" -
在 PyCharm 中可在 Run/Debug Configurations 的 Environment variables 中添加相同配置。
（六）避免同名冲突
若项目根目录或工作目录下存在与第三方包同名的文件/文件夹，Python 会优先加载本地文件。
- 将自定义脚本或文件夹改名，或使用虚拟环境隔离。
（七）使用虚拟环境（强烈推荐）
python -m venv venv
source venv/bin/activate
pip install notebook
- 保障环境隔离，减少全局冲突。
（八）高级排查流程（Mermaid 流程图示例）
五、总结对照表
| 场景 / 问题 | 解决方案 | 示例命令 |
|---|---|---|
| 模块未安装或包名错误 | pip install <正确包名> | pip install notebook |
| 网络不通或超时 | 切换国内源 | pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple |
忘记 import | 在代码中添加 import <module> | import notebook |
缺少 __init__.py | 在包目录下新增空文件 | touch package/__init__.py |
| 包版本与需求不符 | 指定版本安装 | pip install notebook==6.5.1 |
| 自定义包名冲突 | 重命名本地同名文件或文件夹 | mv notebook.py my_notebook.py |
| PYTHONPATH 未设置或不包含目标路径 | 设置环境变量或在 IDE 中配置 | export PYTHONPATH=$PYTHONPATH:/my/modules |
| 不当的相对导入 | 改为绝对导入 | from mypkg.module import func |
| pip 版本过旧 | 升级 pip | pip install --upgrade pip |
| 权限问题 | 使用 sudo 或虚拟环境 | sudo pip install notebook |
更多Bug解决方案请查看==>全栈Bug解决方案专栏https://blog.csdn.net/lyzybbs/category_12988910.html