安装ONNX只需pip install onnx，它仅提供模型格式操作能力；真正运行模型需安装互斥的onnxruntime（CPU）或onnxruntime-gpu（GPU），且GPU版依赖匹配的CUDA驱动与运行时库，并须显式启用CUDAExecutionProvider。
pip install onnx 就够了，这是安装 ONNX 格式工具包的标准命令。它不负责运行模型，只提供模型检查、修改、验证等能力（比如用 onnx.checker.check_model() 验证 .onnx 文件是否合法）。
但你真正想问的，大概率不是这个——而是“怎么装能跑 ONNX 模型的运行时”，也就是 onnxruntime。很多人搜“pip 安装 onnx”结果却卡在 import onnxruntime 报错，就是因为装错了包。
装 onnxruntime 之前必须确认硬件和 CUDA 版本
onnxruntime 和 onnxruntime-gpu 是两个互斥包，不能共存；装错一个，另一个就失效。
没有 NVIDIA GPU，或只打算在 CPU 上跑：
pip install onnxruntime-
有 NVIDIA GPU，且已装好 CUDA 驱动（注意：是驱动，不是 CUDA Toolkit）：
- CUDA 11.x（如 11.8）：直接
pip install onnxruntime-gpu - CUDA 12.x（如 12.2 或 12.4）：必须加额外源
pip install onnxruntime-gpu --extra-index-url <a href="https://www.php.cn/link/0ae444bcc39cbfb377925f6dfa5826af">https://www.php.cn/link/0ae444bcc39cbfb377925f6dfa5826af</a>
- CUDA 11.x（如 11.8）：直接
不确定 CUDA 版本？运行
nvidia-smi查顶部显示的 “CUDA Version”（那是驱动支持的最高 CUDA 版本，不是你装的 Toolkit 版本）
PyCharm / 虚拟环境里 import 失败的常见原因
ModuleNotFoundError: No module named 'onnxruntime' 几乎从不因为包本身有问题，而是环境错位：
- PyCharm 新建项目时没选对 Python 解释器，
pip install装到了系统 Python，但项目用的是虚拟环境 - 终端里激活了 venv，但 PyCharm 的 Python 解释器设置仍指向全局 Python
- 在 Conda 环境里混用 pip（尤其
conda install和pip install交叉使用），可能触发二进制不兼容 - Windows 下用了 PowerShell 而没执行
venv\Scripts\Activate.ps1（默认被策略阻止），导致 pip 实际装到全局
验证是否装对了：在目标环境中运行python -c "import onnxruntime; print(onnxruntime.<strong>version</strong>, onnxruntime.get_device())"
输出带 'GPU' 才说明 GPU 版生效了。
别用 pip 强装 onnxruntime-gpu 到无 GPU 机器
有人图省事，在笔记本上也硬装 onnxruntime-gpu，结果运行时报类似错误：ONNXRuntimeError: [ONNXRuntimeErrorCode:1] : Load model failed: The specified module could not be found.
这不是模型问题，是 onnxruntime-gpu 依赖的 CUDA DLL（如 cublas64_11.dll）根本不存在。Windows 不报具体缺哪个文件，Linux 会提示 libcuda.so.1: cannot open shared object file。
更隐蔽的坑是：某些云服务器（如 AWS g4dn）默认装了 NVIDIA 驱动但没装 CUDA Toolkit，onnxruntime-gpu 仍会加载失败——它需要的是驱动 + 对应版本的 CUDA 运行时库，二者缺一不可。
实际部署时最容易被忽略的一点：ONNX Runtime 的 GPU 支持不是“装了就自动加速”。你得显式启用 CudaExecutionProvider，否则即使 get_device() 返回 'GPU'，推理也可能仍在 CPU 上走。初始化 session 时漏掉 providers=['CUDAExecutionProvider']，等于白装。
