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

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

摘要

在日常Python开发中，我们经常会通过 pip install 安装第三方依赖库。但在 PyCharm控制台 或 终端 中执行时，常常会遇到形如：

ModuleNotFoundError: No module named 'onnxruntime'

这样的报错。
这种问题往往困扰着不少开发者，特别是在配置环境、虚拟环境切换、包依赖冲突等情况下。本文将深入剖析这种问题的开发场景、技术细节，并提供多种解决思路，帮助大家快速定位并修复。

---

一、开发场景背景

这种异常一般出现在以下场景：

• 刚创建新项目：PyCharm新建Python项目，未正确选择解释器或虚拟环境。
• pip安装后仍报错：已经执行了 pip install onnxruntime，但导入时报 ModuleNotFoundError。
• 跨平台开发：Mac、Windows 或 Linux 不同环境下，pip路径和Python解释器不一致。
• 包管理混乱：本地同时存在多个Python版本（如Python 3.9 / 3.11），导致pip安装到了错误的环境中。

---

二、开发环境说明

• 系统：macOS Sonoma
• Python：3.11
• IDE：PyCharm 2025 专业版
• 包管理器：pip (默认自带)

---

三、常见原因分析与解决方案

1. 模块未安装或包名错误

pip install onnxruntime

安装后确认是否能导入：

import onnxruntime

⚠️ 注意：包名和模块名有时不同，例如 pip install opencv-python 对应 import cv2。

---

2. 网络问题，需切换国内源

由于网络原因，pip install 下载可能超时。可配置国内镜像源。

📄 pip.conf (macOS/Linux)：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

📄 pip.ini (Windows)：

[global]
index-url = https://mirrors.aliyun.com/pypi/simple

---

3. 忘记 import

有时并不是安装问题，而是代码里忘写：

import onnxruntime

---

4. 缺少 __init__.py

若是自建module，目录下必须有 __init__.py 文件，否则不会被识别为包。

---

5. 版本冲突

onnxruntime 依赖 numpy，可能需要升级：

pip install --upgrade numpy onnxruntime

---

6. 包名冲突

若你自己写了一个 onnxruntime.py 文件，可能会覆盖官方库。检查并重命名。

---

7. PYTHONPATH 未配置

确认环境变量：

echo $PYTHONPATH

如未设置，将项目路径加入 PYTHONPATH。

---

8. 相对导入问题

在包结构中，避免使用：

from .onnxruntime import ...

改为绝对导入。

---

9. pip版本过低

升级pip：

python -m pip install --upgrade pip

---

---

四、可视化解决流程

---

五、总结表格

问题原因	典型表现	解决方案
包未安装	报错：ModuleNotFoundError	pip install 包名
网络问题	下载超时	使用国内源配置
忘记 import	代码缺少 import	补充 import 包名
缺少 __init__.py	自定义包不识别	新建 __init__.py
版本不兼容	安装后仍失败	pip install --upgrade 包名
包名冲突	自建包同名	重命名文件
环境变量缺失	import 路径错误	设置 PYTHONPATH
相对导入错误	相对路径 import 失败	改用绝对导入
pip版本过低	安装失败	升级pip

---

六、拓展解决思路

除了以上方案，还可以考虑：

• 使用 conda 管理环境（避免pip冲突）。
• 在 PyCharm设置 → Interpreter → 手动安装依赖。
• 使用 requirements.txt 管理版本。
• 借助 Docker 统一环境，避免本地差异。
• 查看 onnxruntime官方安装文档。

---

七、温馨提示🔔

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

---

八、作者名片

作者✍️名片

---