OpenPose 安装前置条件完整指南：Ubuntu / macOS / Windows 三平台依赖环境搭建

OpenPose 安装前置条件完整指南：Ubuntu / macOS / Windows 三平台依赖环境搭建

【免费下载链接】openposeOpenPose: Real-time multi-person keypoint detection library for body, face, hands, and foot estimation项目地址: https://gitcode.com/gh_mirrors/op/openpose

导读：本文以 OpenPose 官方安装文档中的「Prerequisites（前置条件）」一章为骨架，系统梳理从源码编译 OpenPose 前必须完成的全部环境准备：CUDA/cuDNN 版本选型与 GPU 兼容性、CMake GUI 安装、Caffe/OpenCV 依赖、模型文件下载，以及 Ubuntu、macOS、Windows 三平台各自的差异化步骤。读完本文，你将能按平台逐一核对依赖清单，避免因 CUDA 版本不匹配、Anaconda 冲突、防火墙拦截模型下载等高频问题导致编译失败。本文所有命令与结论均以当前仓库 doc/installation/1_prerequisites.md 及配套脚本（scripts/ubuntu/install_deps.sh、scripts/ubuntu/install_cuda.sh、models/getModels.sh 等）为准。

OpenPose 是面向实时多人关键点检测的开源库，支持身体（body）、面部（face）、手部（hand）与脚部关键点估计，其默认后端为 Caffe，并依赖 CUDA（Nvidia GPU）、OpenCL（AMD GPU）或纯 CPU 三种计算路径之一完成推理加速。本文所述的前置条件是后续 doc/installation/0_index.md 中「克隆仓库 → CMake 配置 → 编译 → 运行」整个流程的第一步，也是绝大多数安装报错的根源所在。

一、通用前置要点（三个平台通用）

1. CUDA 版本与显卡架构必须匹配

官方文档将这一条列为「非常重要」，因为它能避免大量安装 bug：请安装最新的 CUDA 版本，或者确保你的 GPU 与系统中的 CUDA 版本兼容。典型对应关系为：

• Nvidia 30XX 系列 GPU：至少需要 CUDA 11；
• GTX 20XX、V100、Volta 或 Turing 架构 GPU：至少需要 CUDA 10。

这条规则背后的实现依据可以在 cmake/Cuda.cmake 中看到：项目按 GPU 架构维护了KEPLER / MAXWELL / PASCAL / VOLTA / TURING / AMPERE等架构集合，其中 Ampere（对应 30XX 系列）明确标注AMPERE "80 86"，且注释要求Ampere (CUDA >= 11)，与文档描述完全一致。CMake 在配置阶段通过op_detect_installed_gpus()自动探测本机 GPU 架构，并据此生成 nvcc 的-gencode arch=...,code=sm_...编译参数；若探测失败则回退为按全部已知架构编译。这意味着 CUDA 工具链版本过低时，根本无法为新一代显卡生成可执行二进制。

2. 模型文件下载与防火墙/公司网络问题

CMake 在配置阶段会自动下载 OpenPose 所需的全部模型，但部分防火墙或公司网络会拦截这些下载。若遇到下载失败，需要手动下载并放置到指定目录。官方给出的模型清单及目标路径如下：

这些模型对应的网络结构文件（.prototxt）已随仓库提供，例如 models/pose/body_25/pose_deploy.prototxt、models/pose/coco/pose_deploy_linevec.prototxt、models/pose/mpi/pose_deploy_linevec.prototxt、models/face/pose_deploy.prototxt 与 models/hand/pose_deploy.prototxt；缺失的只是训练好的.caffemodel权重文件。

仓库同时提供了两条官方下载脚本，其目标目录与上述表格完全一致：

• Ubuntu / Mac 用户可执行 models/getModels.sh，脚本内部以wget -c（支持断点续传）从http://vcl.snu.ac.kr/OpenPose/models/依次拉取 BODY_25、COCO、MPI、Face、Hand 共 5 个权重文件；
• Windows 用户可执行 models/getModels.bat，它复用仓库内自带的 3rdparty/windows/wget/wget.exe 完成同样的下载流程。

需要注意的是：Windows 便携版（Portable Demo）解压后约需额外下载约 500 MB 的模型文件，请预留足够的磁盘与网络带宽。

二、Ubuntu 前置条件

1. 首要警告：Anaconda 必须卸载或停用

Anaconda 不应安装在系统中，或必须处于停用状态。原因在于 Anaconda 自带一个与 Caffe 不兼容的 Protobuf 版本。官方给出了两条出路：

• 卸载 Anaconda，并通过apt-get安装 protobuf；
• 或者停用 Conda 环境：执行conda deactivate（若你当前不在 base 环境，需要连续执行两次）。

这与文档后续要求的sudo apt install protobuf-compiler libgoogle-glog-dev是配套的——只有系统级 protobuf 才能与 OpenPose 内部的 Caffe 构建链路兼容。

2. 安装 CMake GUI

CMake 版本要求>= 3.12，但不同 Ubuntu 版本的安装方式差异很大：

• Ubuntu 20：直接运行sudo apt-get install cmake-qt-gui。
• Ubuntu 18：必须从源码编译 CMake-gui。默认通过sudo apt-get install cmake-qt-gui安装的 CMake-gui（3.10 版）会引发一些编译错误。官方给出的完整步骤为：
  1. 卸载现有版本：sudo apt purge cmake-qt-gui；
  2. 安装构建 CMake 所需的 OpenSSL：sudo apt install libssl-dev；
  3. 安装 Qt5 基础开发包：sudo apt-get install qtbase5-dev；
  4. 从 CMake 官网下载「Latest Release」中的CMake Unix/Linux Source，即cmake-X.X.X.tar.gz；
  5. 解压并进入该目录；
  6. 运行./configure --qt-gui，确认无报错；
  7. 运行./bootstrap && make -j`nproc` && sudo make install -j`nproc`，确认无报错；
  8. 记下 CMake 源码目录路径{CMAKE_FOLDER_PATH}——后续文档中凡是提到cmake-gui的地方，都需要替换为{CMAKE_FOLDER_PATH}/bin/cmake-gui来执行。
• Ubuntu 14 或 16：直接运行sudo apt-get install cmake-qt-gui。若你更倾向纯命令行方式配置 CMake，可参考 doc/installation/0_index.md 中的「CMake Command Line Configuration (Ubuntu Only)」小节，以及 doc/installation/2_additional_settings.md 中的对应段落。

3. Nvidia GPU 版本前置条件（CUDA + cuDNN）

官方测试过的版本组合（强烈推荐照搬）

官方明确说明：OpenPose 在 Ubuntu 20 上以 CUDA 11.7.1（cuDNN 8.5.0）组合进行了大量测试；更早的 OpenPose 版本（v1.6.X、v1.5.X）则在 Ubuntu 18 + CUDA 10.1（cuDNN 7.5.1）与 Ubuntu 14/16 + CUDA 8.0（cuDNN 5.1）上测试。强烈建议使用上述组合以将安装问题最小化。其他组合理论上可用，但官方不为任何 CUDA/cuDNN 与 OpenPose 集成的安装/编译问题提供支持。

一个容易被忽略的细节：如果系统开启了 Secure Boot（默认未开启），MOK 密钥安装步骤可能是强制性的。若自动安装失败，需要记录公钥输出路径，并手动执行sudo mokutil --import PATH_TO_PUBLIC_KEY。

升级显卡驱动

将 Nvidia 驱动升级到最新版本。Ubuntu 20 官方提供的是 515.65 版本驱动。

CUDA 安装

如果对 CUDA 安装不熟悉，官方脚本一键安装是最省事的方式：

sudo bash ./scripts/ubuntu/install_cuda.sh

阅读 scripts/ubuntu/install_cuda.sh 可以看到，该脚本会根据lsb_release -r检测 Ubuntu 版本并自动下载对应发行包：

• Ubuntu 14/16：安装 CUDA 8.0（通过cuda-repo-ubuntu1404/1604-8-0-local-ga2仓库包 +sudo apt-get install cuda-8-0）；
• Ubuntu 18：安装 CUDA 10.2 仓库包（cuda-repo-ubuntu1804-10-2-local，并需apt-key add导入公钥）；
• Ubuntu 20：安装 CUDA 11.0.3 仓库包。

注意：脚本头部声明它假设「Ubuntu 20/18 + Nvidia 显卡 >= 10XX」或「Ubuntu 16/14 + 显卡至 10XX」，否则可能失败。脚本注释还提示：若需要比脚本内置版本更新的 CUDA，应自行下载安装。

熟悉 CUDA 的高级用户也可以手动安装，官方推荐路径：

• Ubuntu 20（CUDA 11.7.1）：从 Nvidia 官网下载 CUDA 11.7.1。绝大多数 Ubuntu 机器使用x86_64架构；官方个人推荐runfile (local)安装器类型，然后按 Nvidia 官网说明安装。安装时务必启用usr/local/cuda下的符号链接，以最大限度减少后续潜在错误；如果驱动是手动安装的，请取消勾选「install driver」选项。
• Ubuntu 18（CUDA 10.1）：与 Ubuntu 20 的步骤类似，仅将 CUDA 版本换成 10.1。
• Ubuntu 14 或 16（CUDA 8 或 10）：运行sudo ./scripts/ubuntu/install_cuda.sh（适用于 Ubuntu 16/14 且显卡不超过 10XX 系列），或从官网下载安装。

cuDNN 安装

先下载（通常名为cuDNN Library for Linux (x86_64)）：

• Ubuntu 20：cuDNN 8.5.0。官方在文档中特别提示：cuDNN 目前因性能退化问题（issue #1864）而不被推荐，安装时应知悉这一取舍；
• Ubuntu 18：cuDNN 7.5.1；
• Ubuntu 14 或 16（cuDNN 5.1 或 7.2）：运行sudo ./scripts/ubuntu/install_cudnn_up_to_Ubuntu16.sh（适用于 Ubuntu 16/14 且显卡不超过 10XX），或从官网手动下载。

再手动安装（适用于任意版本）：解压后将内容复制（合并）到 CUDA 目录。Ubuntu 下通常是/usr/local/cuda-{version}/，Windows 下通常是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v{version}\。

仓库脚本 scripts/ubuntu/install_cudnn_up_to_Ubuntu16.sh 展示了自动化方式：针对 Ubuntu 14/15/16，wget下载 cuDNN 5.1 的 tgz 包后执行sudo tar -xzf cudnn-8.0-linux-x64-v5.1.tgz -C /usr/local解压到/usr/local，再执行sudo ldconfig刷新动态链接库缓存；若检测不到支持的 Ubuntu 版本，脚本会明确提示需从 Nvidia 官网手动安装。

关于 cuDNN 的检测，可在 cmake/Cuda.cmake 的detect_cuDNN()中看到：CMake 通过查找cudnn.h与libcudnn.so（macOS 下为libcudnn.dylib）来定位 cuDNN，并解析cudnn_version.h/cudnn.h中的版本宏，最终校验 cuDNN 主版本必须大于 3，否则报FATAL_ERROR。

4. OpenCL / AMD GPU 版本前置条件

仅在没有 Nvidia GPU、且希望在 AMD 显卡上运行时才需要关注：

• Ubuntu 20 或 18：未经测试且不受官方支持，自行尝试需承担风险。若没有 Nvidia GPU，官方建议直接使用 CPU 版本。
• Ubuntu 14 或 16：
  1. 从 AMD 官方 ROCM 驱动页面下载适用于 Ubuntu 的 3rd party ROCM 驱动；
  2. 安装 ViennaCL 开发库：sudo apt-get install libviennacl-dev。

仓库脚本 scripts/ubuntu/install_deps.sh 中可见，OpenCL 相关依赖（opencl-headers、ocl-icd-opencl-dev、libviennacl-dev）也只在 Ubuntu 14～18 范围内安装，Ubuntu 20 之后官方已放弃支持，与文档表述一致。

5. 安装 Caffe、OpenCV 及 Caffe 前置依赖

OpenPose 默认在底层使用 Caffe 推理引擎，因此环境准备的核心是 Caffe 及其依赖：

• OpenCV：必须已安装。可用sudo apt-get install libopencv-dev安装，也可以使用自己编译的 OpenCV 版本（后续在 doc/installation/2_additional_settings.md 的「Custom OpenCV」小节可配置）。
• Caffe 前置依赖：如果此前没有用过 Caffe，在安装好目标 CUDA 与 cuDNN 之后，运行：

sudo bash ./scripts/ubuntu/install_deps.sh

查看 scripts/ubuntu/install_deps.sh 可知，该脚本按序安装：

1. 基础工具：build-essential；
2. Caffe 通用依赖：libatlas-base-dev、libprotobuf-dev、libleveldb-dev、libsnappy-dev、libhdf5-serial-dev、protobuf-compiler，以及--no-install-recommends方式安装的libboost-all-dev；
3. 其余依赖：libgflags-dev、libgoogle-glog-dev、liblmdb-dev（LMDB 仅在 Caffe 训练时需要，纯推理场景通常用不到）；
4. Python2/3 库：根据系统版本安装pythonX-setuptools、pythonX-dev、pip，并升级numpy、protobuf、opencv-python（Python2 在 Ubuntu 20 官方已停止支持，脚本仅在 14～18 上处理 Python2）；
5. OpenCL 通用依赖（Ubuntu 14～18）：opencl-headers、ocl-icd-opencl-dev、libviennacl-dev。

• CMake 配置生成前置依赖（可能已默认安装）：sudo apt install protobuf-compiler libgoogle-glog-dev。
• OpenPose make 编译前置依赖（可能已默认安装）：sudo apt install libboost-all-dev libhdf5-dev libatlas-base-dev。

6. Python 前置条件（可选，仅使用 Python API 时需要）

需要python-dev、Numpy（数组管理）与 OpenCV（图像加载）。官方给出 Python 2 与 Python 3 两套命令：

# Python 3 (default and recommended) sudo apt-get install python3-dev sudo pip3 install numpy opencv-python # Python 2 sudo apt-get install python-dev sudo pip install numpy opencv-python

官方默认推荐 Python 3。仓库中的 Python API 位于 python/openpose/，通过 pybind11（见 3rdparty/pybind11/）封装 C++ 核心库，因此确保本步骤依赖齐全后，还需在 CMake 配置阶段开启BUILD_PYTHON标志（参见 doc/installation/0_index.md 的 CMake 配置小节）。

三、Mac OS 前置条件

macOS 平台的前置步骤相对简洁：

1. 安装 Homebrew：若没有brew，在终端执行bash scripts/osx/install_brew.sh。仓库脚本 scripts/osx/install_brew.sh 会先执行xcode-select --install（已安装时命令返回非零码但不会中断脚本），随后拉取并运行 Homebrew 官方安装脚本，最后brew update。
2. 安装 CMake GUI：执行brew install --cask cmake。
3. 安装 Caffe、OpenCV 及 Caffe 前置依赖：执行bash scripts/osx/install_deps.sh。

查看 scripts/osx/install_deps.sh 可知，该脚本通过 brew 批量安装openblas snappy leveldb gflags glog szip lmdb hdf5 opencv protobuf boost cmake viennacl（对已安装的包执行brew upgrade），并通过pip安装numpy<1.17与opencv-python<4.3的 Python2 依赖。脚本注释还保留了构建 Python pycaffe 时需从源码编译 protobuf 与 boost(+python) 的可选方案。

需要留意的是，macOS 上若使用 Nvidia GPU，还需遵循与 Ubuntu 相同的 CUDA/cuDNN 版本匹配原则（参见上文「CUDA 版本与显卡架构必须匹配」）；若使用 AMD 显卡，则对应 OpenCL 路径（macOS 上 AMD 显卡有专门的特殊安装说明，见 doc/installation/2_additional_settings.md 的 OpenCL Version 小节）。此外，cmake/Cuda.cmake 针对 macOS 有专门处理：检测 Darwin 版本、为CUDA_VERSION < 7.0配置 libstdc++/libc++ 选项，并向 nvcc 追加-Xcompiler -Wno-unused-function等标志。

四、Windows 前置条件

注意：本节指令仅在从源码编译 OpenPose 时需要。若只想使用 Windows 便携版（Portable Demo）二进制，请直接跳过本节。

1. 安装 CMake GUI

从 CMake 官网下载「Latest Release」中的Windows win64-x64 Installer，即cmake-X.X.X-win64-x64.msi，安装即可。

2. 安装 Microsoft Visual Studio

支持VS 2019 Enterprise、VS 2017 Enterprise或VS 2015 Enterprise Update 3：

• 重要：在勾选安装组件时，务必启用所有与 C++ 相关的选项（all C++-related flags）。
• 若使用VS 2019 Community（或 2017 Community）：官方不正式支持，但理论上与 Enterprise 版运行方式类似。

3. Nvidia GPU 版本前置条件

官方测试过的版本组合

官方明确说明：OpenPose 在 VS2019 上以 CUDA 11.1.1（cuDNN 8.1.0）组合进行了大量测试；更早版本（v1.6.X、v1.5.X）则在 VS2017 + CUDA 10.1（cuDNN 7.5.1）与 VS2015 + CUDA 8.0（cuDNN 5.1）上测试。同样地，强烈推荐使用这些组合，其他组合虽然可能可用，但官方不提供安装/编译问题的支持。

升级显卡驱动

在 Nvidia「GeForce Experience」软件或 Nvidia 官网将驱动升级到最新版本。

CUDA 安装

在 CUDA 11.1.1、CUDA 10.1 与 CUDA 8 三者中选择一个安装：

• 安装顺序非常关键：必须先装好 Visual Studio 2019/2017/2015，再安装 CUDA，以保证 CUDA 安装程序能为 VS 生成全部必需文件。如果 CUDA 先于 VS 安装，则需要重装 CUDA。
• 重要排错提示：若 CMake 报出类似CUDA_TOOLKIT_ROOT_DIR not found or specified或其他 CUDA 组件缺失的错误，请按顺序执行：1）重装 Visual Studio 2015；2）重启电脑；3）重装 CUDA。

cuDNN 安装

对应版本为 cuDNN 8.1.0、cuDNN 7.5.1 或 cuDNN 5.1。手动安装方式与 Ubuntu 完全一致：解压后将内容复制（合并）到 CUDA 目录，Windows 下通常是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v{version}（Ubuntu 下为/usr/local/cuda-{version}/）。

4. AMD GPU 版本前置条件

仅在没有 Nvidia GPU、且希望在 AMD 显卡上运行时需要：

1. 从 AMD 官网下载 Windows 官方 AMD 驱动；
2. libviennacl包已随 OpenPose 的 Windows 发行版内置，无需额外操作。

5. Caffe、OpenCV 及 Caffe 前置依赖

CMake 会自动下载全部 Windows DLL；当然也可以选择手动下载。注意：请将 zip 文件保留在3rdparty/windows/目录下，这样 CMake 就不会再次尝试下载它们。各依赖及解压目标如下：

从仓库结构可以看到，3rdparty/windows/ 下确实预置了wget.exe（供 models/getModels.bat 使用）以及getCaffe.bat、getCaffe3rdparty.bat、getOpenCV.bat、getSpinnaker.bat、getFreeglut.bat等辅助下载脚本，它们分别对应上表中的 Caffe、Caffe 依赖、OpenCV、Spinnaker（3D 相机模块）与 FreeGLUT（3D 可视化）的自动获取流程。

6. Python 前置条件（可选）

仅在使用 Python API 时需要：安装任意 Windows 版 Python 3.X，然后：

sudo pip install numpy opencv-python

五、前置条件就绪之后

完成上述平台对应的前置条件后，即可进入正式安装流程：

1. 阅读 doc/installation/0_index.md 的「Compiling and Running OpenPose from Source」章节：克隆仓库（git clone+git submodule update --init --recursive --remote）、在build/目录打开 CMake-GUI 完成Configure/Generate（期间按需设置BUILD_PYTHON与GPU_MODE标志）、随后make -jnproc``（Windows 为 VS 解决方案中 F7 编译）；
2. 需要更多可选配置（自定义 Caffe/OpenCV、OpenCL 版本、COCO/MPI 模型、3D 重建与标定模块、最大速度优化等）时，参见 doc/installation/2_additional_settings.md；
3. 编译完成后，参照 doc/01_demo.md 运行第一个 demo 验证安装是否成功；若运行期出现Cuda check failed (3 vs. 0): initialization error，通常是驱动与 CUDA 版本不一致所致，可参考 doc/installation/0_index.md 中「Windows Portable Demo」一节的排查建议（升级驱动、统一或卸载本机 CUDA 版本）；
4. 遇到其他安装问题，优先查阅 doc/05_faq.md，或按官方模板提交 issue——重复提问、以及单纯针对 Caffe/OpenCV/CUDA 安装错误的 issue 不会被回复。

总而言之，OpenPose 编译成功的先决条件可浓缩为一句话：在正确的操作系统版本上，安装与你的 GPU 架构匹配的 CUDA/cuDNN 组合，用系统包管理器（而非 Anaconda）提供 protobuf 等 Caffe 依赖，并保证 OpenCV 与模型文件就位。对照本文的平台清单逐项核对，即可将安装失败的概率降到最低。

【免费下载链接】openposeOpenPose: Real-time multi-person keypoint detection library for body, face, hands, and foot estimation项目地址: https://gitcode.com/gh_mirrors/op/openpose