解决onnxruntime安装失败：跨平台预编译包与源码编译实战指南

1. 问题现象与核心痛点剖析

最近在部署一个基于YOLO模型的边缘计算项目时，我遇到了一个非常典型且恼人的问题：尝试通过pip install onnxruntime安装最新版本时，命令行卡住或者直接报错，提示找不到满足要求的版本。更具体地说，我的环境是一台搭载国产CPU的服务器，系统是Ubuntu 22.04，Python版本是3.9。我的需求很明确，需要安装一个较新版本的onnxruntime（比如1.16.0+）来获得对最新ONNX算子集和性能优化的支持，但pip仓库里似乎永远只有1.14.x甚至更老的版本。这个问题不仅出现在国产CPU平台，很多使用Windows、macOS ARM芯片（M1/M2/M3）或者在Jetson Orin Nano这类边缘设备上使用JetPack 5.1.1的朋友，都反馈过类似遭遇。表面上看是“安装失败”，但背后其实是Python包分发生态中一个关于平台兼容性和预编译二进制包的经典难题。

简单来说，onnxruntime作为一个对计算性能有极高要求的推理引擎，其官方PyPI包（onnxruntime）主要提供的是针对x86-64 CPU和CUDA的预编译轮子文件（.whl）。当你执行pip install onnxruntime时，pip会去PyPI查找与你当前操作系统和Python版本匹配的.whl文件。如果你的平台不在官方预编译的支持列表里（比如国产的ARM架构CPU、苹果Silicon、或者特定的Linux发行版搭配特定GLIBC版本），pip就找不到合适的.whl文件，它会退而求其次尝试从源代码（sdist）编译安装。而从源码编译onnxruntime需要一整套复杂的C++构建环境（CMake、编译器、依赖库等），对绝大多数用户来说，这几乎是一个不可能完成的任务，最终导致安装失败或无限期卡住。

2. 解决方案总览：绕过官方PyPI的四种路径

面对无法通过pip install onnxruntime直接安装新版本的问题，我们不能在一棵树上吊死。经过多次实践，我梳理出四条切实可行的路径，它们适用于不同的场景和需求。你可以根据你的具体环境（操作系统、CPU架构、是否有GPU）来选择。

路径一：安装特定平台的分发包这是最推荐、最省事的方法。微软为onnxruntime维护了多个不同的PyPI包，针对不同的硬件加速后端。最常用的是onnxruntime-gpu（用于NVIDIA GPU）和onnxruntime-directml（用于Windows AMD/Intel GPU）。但更重要的是，对于ARM架构（包括苹果M系列、国产飞腾/鲲鹏、Jetson），你应该安装onnxruntime包，但必须指定一个包含平台标识的版本文件名，这通常需要手动下载.whl文件。

路径二：从源码编译安装这是最彻底、最灵活的方法，可以生成完全适配你本地环境的二进制文件。但过程繁琐，对系统环境要求高，适合有定制化需求（如开启特定算子、修改源码）或官方确实未提供预编译包的极端情况。

路径三：使用Docker容器如果你只是想运行环境，而不是开发，那么使用官方或社区维护的Docker镜像是绝佳选择。它能完美解决环境隔离和依赖问题，特别适合在服务器上部署。

路径四：利用conda或系统包管理器在某些Linux发行版或通过Anaconda/Miniconda环境中，conda-forge频道或系统仓库可能提供了预编译的onnxruntime包。这通常比从PyPI安装更稳定。

接下来，我将重点详解最实用的路径一和路径二，并提供详细的步骤和避坑指南。

2.1 为什么pip install onnxruntime会失败？

理解失败原因是解决问题的第一步。当你运行pip install onnxruntime==1.16.0时，背后发生了这些事情：

1. 查询PyPI：pip向PyPI服务器发送请求，查询onnxruntime包的所有发布版本和文件。
2. 匹配平台标签：pip会根据你的环境生成一个“平台标签”，例如cp39-cp39-manylinux_2_17_x86_64（表示Python 3.9，兼容性强的Linux，x86_64架构）。它会在包的文件列表中寻找匹配此标签的.whl文件。
3. 找不到匹配项：对于onnxruntime，官方主要上传manylinux_x86_64和win_amd64的轮子。如果你的平台标签是manylinux_2_17_aarch64（ARM64）或macosx_11_0_arm64（Apple Silicon），那么pip在官方onnxruntime包下就找不到任何匹配的预编译二进制文件。
4. 回退到源码：当没有合适的.whl文件时，pip会尝试下载源代码包（通常是.tar.gz文件）并在本地编译。onnxruntime的源码编译需要CMake、C++编译器（如g++）、Python开发头文件以及可能的CUDA、MKL等依赖。这个配置过程极其复杂，缺少任何一个环节都会导致编译失败。
5. 最终结果：你看到的就是长时间的“Building wheel for onnxruntime”然后失败，或者直接报错 “Could not find a version that satisfies the requirement”。

注意：有时候即使平台匹配（比如x86_64的Windows），pip也可能只提供旧版本。这是因为包维护者可能没有为所有版本都上传所有平台的轮子。新版本的轮子可能还在构建或上传中。

3. 核心解决方案详解：手动下载与安装预编译Whl文件

这是解决此问题最高效、最常用的方法。核心思路是：我们不依赖pip自动查找，而是直接找到为我们平台预编译好的.whl文件，然后使用pip install <whl文件路径>进行本地安装。

3.1 确定你的系统平台标识

首先，你需要知道你的Python环境期待什么样的文件名。打开终端或命令提示符，运行以下命令：

python -c "import pip; print(pip._internal.pep425tags.get_supported())"

或者使用更现代的方式（Python 3.8+）：

python -c "import sys; from pip._vendor import packaging; print([f'{packaging.tags.interpreter_name()}-{packaging.tags.interpreter_version()}-{tag}' for tag in packaging.tags.sys_tags()])"

你会得到一长串列表，如cp39-cp39-manylinux_2_17_x86_64，cp39-cp39-manylinux_2_17_aarch64，cp39-cp39-win_amd64等。你需要关注的是第一个或前几个。其中关键部分是：

• cp39: 表示CPython 3.9。
• manylinux_2_17_x86_64: 表示适用于GLIBC 2.17+的Linux系统，x86_64架构。
• manylinux_2_17_aarch64: 表示Linux系统，ARM64架构。
• win_amd64: 表示64位Windows。
• macosx_11_0_arm64: 表示macOS 11.0+，Apple Silicon ARM架构。

记下与你环境最匹配的标签。

3.2 寻找正确的预编译Whl文件

官方发布的预编译包主要在两个地方：

1. onnxruntime官方GitHub Releases：这是最全的来源。访问 onnxruntime GitHub Releases页面 。找到你想要的版本（例如1.16.0），在“Assets”下拉列表中，你会看到大量以.whl结尾的文件。文件名通常遵循以下模式：

   • onnxruntime-{version}-{python_tag}-{abi_tag}-{platform_tag}.whl
   • 例如：onnxruntime-1.16.0-cp39-cp39-manylinux_2_17_aarch64.whl（Linux ARM64, Python 3.9）
   • 例如：onnxruntime-1.16.0-cp39-cp39-win_amd64.whl（Windows x64, Python 3.9）
   • 例如：onnxruntime-1.16.0-cp39-cp39-macosx_11_0_arm64.whl（macOS Apple Silicon, Python 3.9）

2. PyPI的下载页面：你也可以直接访问https://pypi.org/project/onnxruntime/{version}/#files，这里列出了该版本所有上传的文件。但GitHub Releases通常更直观。

针对特定场景的找包技巧：

• 国产CPU（如飞腾、鲲鹏）：这些通常是ARM64架构。请寻找包含aarch64或arm64的whl文件。注意，manylinux标签的兼容性较好。如果官方没有提供，可以尝试寻找社区维护的版本，或者考虑从源码编译。
• NVIDIA Jetson (Orin Nano, JetPack 5.1.1)：Jetson也是ARM64架构，但运行的是Ubuntu。理论上，通用的manylinux_2_17_aarch64whl文件可能可以工作。但更推荐使用NVIDIA官方为Jetson提供的TensorRT后端，即安装onnxruntime-gpu的Jetson专用版本，或者使用包含TensorRT EP（Execution Provider）的社区构建版本。有时你需要用jetson作为关键词在文件名中搜索。
• 苹果M系列芯片：直接寻找macosx_11_0_arm64标签的文件。从onnxruntime 1.14开始，官方提供了对Apple Silicon的官方支持。

3.3 下载并安装Whl文件

假设我们为Linux ARM64 (Python 3.9) 环境找到了onnxruntime-1.16.0-cp39-cp39-manylinux_2_17_aarch64.whl文件。

1. 下载：直接从GitHub Releases页面点击下载该文件，或者使用wget/curl命令。

   wget https://github.com/microsoft/onnxruntime/releases/download/v1.16.0/onnxruntime-1.16.0-cp39-cp39-manylinux_2_17_aarch64.whl

2. 安装：使用pip进行本地安装。确保当前目录下有下载的whl文件。

   pip install onnxruntime-1.16.0-cp39-cp39-manylinux_2_17_aarch64.whl

   如果一切顺利，pip会直接安装这个预编译的轮子，速度非常快。

3. 验证安装：

   python -c "import onnxruntime as ort; print(ort.__version__); print(ort.get_available_providers())"

   这将打印出onnxruntime的版本和可用的执行提供程序（如CPU、CUDA等）。

实操心得：在下载whl文件前，务必核对Python版本（cp39）、系统（manylinux/win/macosx）和架构（x86_64/aarch64/arm64）是否完全匹配。一个常见的错误是，在64位系统上误下了32位（win32）的包，或者在Python 3.8环境下试图安装cp39的包。不匹配会导致安装失败，提示类似 “is not a supported wheel on this platform” 的错误。

4. 进阶方案：从源码编译onnxruntime

当你需要的平台没有预编译包，或者你需要开启某些默认未开启的功能（比如特定的Execution Provider，或启用训练API）时，从源码编译是唯一的选择。这个过程比较耗时，且对环境要求严格。

4.1 编译环境准备（以Ubuntu Linux为例）

以下是在Ubuntu 22.04上编译onnxruntime CPU版本的基本步骤。编译GPU版本需要额外安装CUDA和cuDNN。

1. 安装系统依赖：

   sudo apt update sudo apt install -y build-essential cmake git libpython3-dev python3-pip # 如果需要GPU支持，还需要安装CUDA Toolkit和cuDNN，此处略过。

2. 获取源码：

   git clone --recursive https://github.com/microsoft/onnxruntime cd onnxruntime # 切换到特定版本，例如v1.16.0 git checkout v1.16.0

4.2 配置与编译过程

onnxruntime使用CMake进行构建。我们通过一个辅助的Python脚本build.py来简化流程。

1. 使用build.py脚本编译（推荐）：

   ./build.sh --config Release --build_shared_lib --parallel 8 --skip_tests

   或者，更精细地使用build.py：

   python3 tools/ci_build/build.py \ --build_dir ./build \ --config Release \ --build_shared_lib \ --parallel 8 \ --skip_tests \ --enable_pybind \ --cmake_extra_defines CMAKE_INSTALL_PREFIX=/usr/local

   • --build_dir: 指定构建目录。
   • --config Release: 构建发布版本（性能最优）。
   • --build_shared_lib: 构建共享库（.so文件），这对于Python绑定是必须的。
   • --parallel 8: 使用8个线程并行编译，加快速度。
   • --skip_tests: 跳过单元测试，节省时间。
   • --enable_pybind: 启用Python绑定生成。
   • --cmake_extra_defines: 传递额外的CMake参数，这里设置了安装前缀。

2. 安装Python包： 编译完成后，进入构建目录下的Python输出文件夹进行安装。

   cd build/Linux/Release # 这里会生成一个dist文件夹，里面包含编译好的whl文件 pip install dist/onnxruntime-*.whl

   你也可以直接使用setup.py从编译产物中安装：

   cd onnxruntime pip install -e .

注意事项：源码编译是一个“深坑”，极易因为依赖库版本、编译器版本、系统路径等问题失败。最常见的错误包括：

1. 找不到Python.h：确保安装了python3-dev或python3-devel包。
2. protobuf版本冲突：onnxruntime对protobuf版本有严格要求。建议在干净的虚拟环境（venv或conda）中操作，或者使用项目自带的requirements.txt安装依赖。
3. 内存不足：编译onnxruntime需要大量内存（建议至少8GB）。在内存小的机器上可能因OOM（内存溢出）而失败。
4. 时间过长：在性能一般的机器上，完整编译可能需要1-2小时。请保持耐心，并确保网络稳定（因为脚本会下载一些依赖）。

5. 针对特定场景的安装策略与问题排查

5.1 在Jetson Orin Nano (JetPack 5.1.1) 上安装

Jetson平台是ARM64架构，但拥有NVIDIA GPU。最佳实践是使用支持TensorRT后端的onnxruntime，以获得最佳性能。

1. 尝试通用ARM64包：首先可以尝试安装官方的Linux ARM64 CPU版本，看是否能运行。

   pip install https://github.com/microsoft/onnxruntime/releases/download/v1.16.0/onnxruntime-1.16.0-cp38-cp38-manylinux_2_17_aarch64.whl

   （注意：JetPack 5.1.1 默认Python版本可能是3.8，请对应修改cp标签）

2. 寻找社区提供的TensorRT包：由于官方不直接提供Jetson的GPU包，可以搜索 “onnxruntime jetson whl” 或查看NVIDIA的论坛、博客。有时热心开发者会分享他们编译的版本。

3. 自行编译（终极方案）：在Jetson上从源码编译，并启用TensorRT Execution Provider。这需要先安装好JetPack中的CUDA、cuDNN和TensorRT。编译命令需要额外指定TensorRT的路径：

   ./build.sh --config Release --build_shared_lib --parallel 4 \ --use_tensorrt --tensorrt_home /usr/src/tensorrt \ --cuda_home /usr/local/cuda \ --cudnn_home /usr/lib/aarch64-linux-gnu

   这个过程在Jetson上会非常漫长（可能超过3小时），且对存储空间要求高。

5.2 使用Docker容器

如果你不想污染主机环境，或者主机环境过于复杂，Docker是最干净的解决方案。onnxruntime官方在 Docker Hub 上提供了多个标签的镜像。

1. 拉取并运行CPU镜像：

   docker run -it --rm mcr.microsoft.com/azureml/onnxruntime:latest

   进入容器后，Python环境已经预装了onnxruntime。

2. 使用GPU镜像（需要安装NVIDIA Container Toolkit）：

   docker run -it --rm --gpus all mcr.microsoft.com/azureml/onnxruntime:latest-cuda

3. 构建自定义Dockerfile：你可以基于官方镜像，添加你自己的应用代码和依赖。

   FROM mcr.microsoft.com/azureml/onnxruntime:latest-cuda WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD ["python", "your_script.py"]

5.3 常见错误与排查技巧实录

即使按照上述步骤操作，你也可能会遇到一些“坑”。下面是我在实际操作中遇到的一些典型问题及其解决方法。

问题1：安装whl时提示 “is not a supported wheel on this platform.”

• 原因：whl文件的平台标签与你的Python环境不匹配。
• 排查：再次用python -c “import pip...”命令检查你的平台标签。确认下载的whl文件名中的cpXX,abi,platform部分是否完全一致。例如，在Ubuntu 22.04 (GLIBC 2.35)上，manylinux_2_17的包通常是兼容的，但manylinux_2_12的包可能不行。可以尝试下载manylinux_2_31或manylinux2014等更新兼容性标签的包。

问题2：导入onnxruntime时报错 “ImportError: libxxx.so.xx: cannot open shared object file: No such file or directory”

• 原因：动态链接库缺失。预编译的whl文件可能依赖系统中特定版本的共享库。
• 解决：根据缺失的库名（如libgomp,libprotobuf），使用系统包管理器安装对应的开发包。在Ubuntu上，可以尝试sudo apt install libgomp1 libprotobuf-dev。使用ldd命令可以查看具体依赖哪些库：

  ldd $(python -c “import onnxruntime; print(onnxruntime.__file__)”)

问题3：在Windows上，pip install 卡在 “Building wheel for onnxruntime” 不动

• 原因：pip正在尝试从源码编译，但你的系统缺少编译环境（主要是Visual C++ Build Tools）。
• 解决：
  1. 首选方案：直接去GitHub Releases下载对应你Python版本和系统架构（win_amd64）的.whl文件进行本地安装。
  2. 次选方案：如果你确实需要编译，请安装 Microsoft C++ Build Tools 。安装时务必勾选 “Desktop development with C++” 工作负载。

问题4：版本冲突，例如与onnx包的版本不兼容

• 原因：较新版本的onnxruntime可能需要特定版本以上的onnx包。
• 解决：在安装onnxruntime时，让pip自动解决依赖，或者先升级onnx包。

  pip install --upgrade onnx pip install onnxruntime-xxx.whl

  如果是在虚拟环境中，建议先创建一个干净的环境再安装。

问题5：在Mac M1/M2上，安装后性能极差或报错

• 原因：可能安装了x86_64版本的包，通过Rosetta 2转译运行。
• 解决：确保你下载并安装的是macosx_11_0_arm64标签的whl文件。使用file命令可以检查Python解释器是否是ARM64原生版本：

  file $(which python3)

  输出应包含arm64字样。

6. 总结与最佳实践建议

经过这一番折腾，你应该能成功在目标机器上安装上较新版本的onnxruntime了。回顾整个过程，我想分享几条最重要的经验：

1. 优先寻找预编译包：99%的问题都可以通过找到正确的.whl文件解决。GitHub Releases是你的第一站。养成根据python -c “import pip...”输出的标签去精准搜索文件的习惯。
2. 善用虚拟环境：无论是使用conda还是Python自带的venv，创建一个干净的虚拟环境可以避免绝大多数依赖冲突问题。在安装前后，用pip list对比一下环境变化。
3. 理解平台差异：不同架构（x86 vs ARM）、不同操作系统（Linux发行版、Windows、macOS）、不同Python版本（3.8, 3.9, 3.10）都是独立的“维度”，必须完全匹配。国产CPU、Jetson这类边缘设备属于ARM64架构的Linux，这是一个关键认知。
4. 编译是最后的手段：从源码编译onnxruntime是一项目标明确但过程艰辛的工程。除非有强烈的定制化需求，或者官方/社区确实没有提供预编译包，否则不要轻易尝试。如果必须编译，请预留充足的时间，并准备好查阅官方构建文档和Issue列表。
5. Docker是部署神器：对于生产环境部署，强烈建议使用Docker。它封装了所有依赖，保证了环境一致性，彻底解决了“在我机器上是好的”这类问题。你可以基于官方镜像构建自己的业务镜像。

最后，当你在一个陌生环境（比如一台新的国产服务器）上部署AI模型推理服务时，关于onnxruntime的安装问题很可能只是第一道关卡。后续可能还会遇到模型转换、性能调优、多线程推理等问题。但只要你掌握了“识别平台-寻找匹配包-手动安装”这个核心方法论，至少能在起点上扫清障碍，把精力集中在更有价值的模型优化和业务逻辑开发上。