PyTorch LibTorch C++ 发行版安装实战：从零构建第一个 LibTorch 应用

本文基于 PyTorch 官方 C++ 文档 installing.md 展开，完整讲解 LibTorch 二进制发行版的下载、CMake 集成、最小示例应用的编写与构建全流程，并结合当前仓库源码深入剖析 find_package(Torch) 的底层工作机制、pip 安装场景下的 cmake_prefix_path 定位逻辑，以及从源码构建 libtorch 的替代路径。读完本文，你将能够独立完成一个依赖 LibTorch 的 C++ 应用的工程搭建、编译与运行，并理解其背后的 CMake 配置细节。

LibTorch 是什么：PyTorch 的 C++ 二进制发行版

PyTorch 官方提供了包含全部头文件、库文件和 CMake 配置文件的二进制发行版，官方称之为 LibTorch。它允许你无需接触 Python、也无需编译整个 PyTorch 源码，就能直接以 C++ 方式依赖 PyTorch 的全部张量计算与动态神经网络能力。

从 C++ API 的整体文档结构看（见 docs/cpp/source/index.md），PyTorch 的 C++ 接口大致分为五个部分：

• ATen：基础的张量与数学运算库，是其余所有接口的基石；
• Autograd：在 ATen 之上提供自动求导；
• C++ Frontend：面向模型训练与推理的高层构造（torch::nn、torch::optim、torch::data 等）；
• TorchScript：加载与执行序列化 TorchScript 模型的接口；
• C++ Extensions：为 Python 中的 PyTorch 扩展自定义 C++/CUDA 算子。

官方同时注明 C++ API 目前处于 “beta” 稳定性级别，后端可能存在破坏性变更；而本文所讲的 LibTorch 是这一 C++ API 生态的标准分发形态。LibTorch 发行版内包含了 include/（头文件）、lib/（共享/静态库）与 share/cmake/（CMake 包配置文件）三大目录，这正是后文 find_package(Torch) 能够工作的原因。

第一步：下载 LibTorch 发行版

最小示例的第一步是从 PyTorch 官网（pytorch.org 的 Get Started 页面）下载 LibTorch 的 ZIP 归档。官方文档给出的 CPU 版本示例命令如下：

wget https://download.pytorch.org/libtorch/nightly/cpu/libtorch-shared-with-deps-latest.zip
unzip libtorch-shared-with-deps-latest.zip

需要注意几个版本选择要点：

1. CPU 版与 GPU 版：上面的链接是 仅 CPU 的 LibTorch。如果需要 GPU 支持，必须在官网的版本选择器中挑选与 CUDA 版本、Python 版本匹配的链接（例如 libtorch-cxx11-abi-shared-with-deps-<version>%2Bcu124.zip 这类含 CUDA 后缀的包）。
2. nightly 与 release：链接中的 nightly 表示每日构建，适合尝鲜新特性；生产环境建议使用对应 release 版本的归档。
3. shared 与 static：-shared- 表示提供共享库（libtorch.so），-static- 则提供静态库；with-deps 表示已把第三方依赖一并打包进 lib/。
4. cxx11 ABI：在 Linux 上还存在 cxx11-abi 与普通 ABI 两种变体，需与你自己程序编译时使用的 ABI 保持一致（详见下文的系统要求）。

下载解压后，你将得到一个 LibTorch 根目录，其内部布局大致为：

libtorch/
  include/        # 全部 C++ 头文件
  lib/            # 库文件（.so / .a / .dll）
  share/
    cmake/        # CMake 配置文件（TorchConfig.cmake 等）

Windows 开发者如果不想用 CMake，可以跳过本节直接参考后文的 Visual Studio 扩展方案。

第二步：编写最小 CMake 构建配置

CMake 并不是使用 LibTorch 的硬性要求，但它是官方推荐且长期受良好支持的构建系统。官方文档给出的最基础 CMakeLists.txt 如下（完整继承原文档，并补充了逐项注释）：

cmake_minimum_required(VERSION 3.18 FATAL_ERROR)   # 最低 CMake 版本要求 3.18
project(example-app)

find_package(Torch REQUIRED)                       # 定位 LibTorch，导出 TORCH_* 系列变量
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${TORCH_CXX_FLAGS}")  # 注入 LibTorch 要求的编译标志

add_executable(example-app example-app.cpp)
target_link_libraries(example-app "${TORCH_LIBRARIES}")       # 链接 torch 及全部依赖库
set_property(TARGET example-app PROPERTY CXX_STANDARD 20)      # 要求 C++20 标准

# 以下代码块建议在 Windows 上使用。
# 由于 issue #25457，DLL 需要复制到可执行文件旁以避免内存错误。
if (MSVC)
  file(GLOB TORCH_DLLS "${TORCH_INSTALL_PREFIX}/lib/*.dll")
  add_custom_command(TARGET example-app
                     POST_BUILD
                     COMMAND ${CMAKE_COMMAND} -E copy_if_different
                     ${TORCH_DLLS}
                     $<TARGET_FILE_DIR:example-app>)
endif (MSVC)

关键要素说明：

• find_package(Torch REQUIRED) 是核心：它会在 CMAKE_PREFIX_PATH 指定的前缀下查找 share/cmake/ 中的 TorchConfig.cmake，成功后定义 TORCH_FOUND、TORCH_INCLUDE_DIRS、TORCH_LIBRARIES、TORCH_CXX_FLAGS 等变量；
• set_property(... CXX_STANDARD 20) 要求 C++20。这一点与仓库中 TorchConfig.cmake.in 模板对 torch 导入目标设置 CXX_STANDARD 20 的做法一致（见下文源码剖析）；
• MSVC 分支的 POST_BUILD 命令把 lib/*.dll 复制到输出目录，规避 Windows 下著名的 DLL 缺失导致的内存错误（对应 issue #25457）。

示例程序本身极其简单，创建一个 torch::Tensor 并打印：

#include <torch/torch.h>
#include <iostream>

int main() {
  torch::Tensor tensor = torch::rand({2, 3});
  std::cout << tensor << std::endl;
}

官方文档特别提示：虽然也存在更细粒度的头文件，可以只引入 PyTorch C++ API 的某一部分，但 包含 torch/torch.h 是涵盖大部分功能最稳妥的方式。

第三步：构建并运行

假设示例工程目录结构如下：

example-app/
  CMakeLists.txt
  example-app.cpp

在 example-app/ 目录内执行：

mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=/absolute/path/to/libtorch ..
cmake --build . --config Release

其中 /absolute/path/to/libtorch 必须是绝对路径，指向解压后的 LibTorch 根目录。

pip 安装用户的简化写法：如果 PyTorch 是通过 pip 安装的，CMAKE_PREFIX_PATH 无需手动猜测——官方文档建议直接查询 torch.utils.cmake_prefix_path 变量：

cmake -DCMAKE_PREFIX_PATH=`python3 -c 'import torch;print(torch.utils.cmake_prefix_path)'` ..

这个机制在当前仓库源码中有直接对应：torch/utils/init.py 第 32 行定义了

cmake_prefix_path = _osp.join(_osp.dirname(_osp.dirname(__file__)), "share", "cmake")

即 pip 安装的 torch 包内 torch/share/cmake 目录——其中自带了 TorchConfig.cmake，与 LibTorch ZIP 包中的 share/cmake/ 布局完全同构。这也解释了为什么 pip 包用户不需要单独下载 LibTorch：C++ 扩展（如 torch.utils.cpp_extension）正是复用这一前缀完成链接的。

一切顺利时，configure 阶段输出类似：

-- The C compiler identification is GNU 5.4.0
-- The CXX compiler identification is GNU 5.4.0
-- Check for working C compiler: /usr/bin/cc -- works
-- Looking for pthread.h - found
-- Looking for pthread_create in pthread - found
-- Found Threads: TRUE
-- Configuring done
-- Generating done
-- Build files have been written to: /example-app/build

随后 cmake --build . --config Release 完成编译链接，运行产物：

root@4b5a67132e81:/example-app/build# ./example-app
0.2063  0.6593  0.0866
0.0796  0.5841  0.1569
[ Variable[CPUFloatType]{2,3} ]

具体数值受随机性影响，但应是一个 2×3 的 CPU Float 张量。

Windows 提示：Windows 上 debug 与 release 构建不 ABI 兼容。如果你的项目以 Debug 模式构建，请下载 LibTorch 的 debug 版本，并确保 cmake --build . 时通过 --config 指定了正确的配置。

源码剖析：find_package(Torch) 究竟做了什么

上文 CMake 配置中的几乎所有变量都来自 LibTorch 发行版里的 CMake 配置模板。该模板在 PyTorch 源码树中为 cmake/TorchConfig.cmake.in，构建发行版时经 CMake 配置生成最终的 TorchConfig.cmake。阅读它可以看到几个关键事实：

1. 前缀自定位：模板假定自身位于 <install-prefix>/share/cmake/Torch/TorchConfig.cmake，向上回溯三级得到 TORCH_INSTALL_PREFIX（第 52 行）。因此 CMAKE_PREFIX_PATH 必须指向 LibTorch 根目录而非 share/cmake——这就是构建命令中必须传绝对路径到解压根目录的原因。若设置了环境变量 TORCH_INSTALL_PREFIX 则优先使用。

2. 头文件搜索路径：TORCH_INCLUDE_DIRS 被设为 <prefix>/include 与 <prefix>/include/torch/csrc/api/include（第 56-58 行），后者正是 torch/torch.h 这类高层 API 头文件的所在位置。

3. 共享库与静态库两条路径：

   • 共享库模式（BUILD_SHARED_LIBS=ON，即 libtorch-shared 包）：通过 find_dependency(Caffe2 ...) 引入 torch 导入目标，TORCH_LIBRARIES 由 torch 与 Caffe2_MAIN_LIBS 组成，再追加 c10 等；
   • 静态库模式（libtorch-static 包）：模板显式用 append_wholearchive_lib_if_found 以 whole-archive 方式把 torch、torch_cpu（以及 GPU 包中的 torch_cuda、c10_cuda）拉入链接，并按平台选择不同归档标志（macOS 用 -Wl,-force_load，MSVC 用 -WHOLEARCHIVE:，Linux 用 -Wl,--whole-archive ... --no-whole-archive），随后逐一追加 c10、protobuf、onnx、fmt、pthreadpool 等依赖库。

4. C++20 标准：模板对 torch 目标设置 CXX_STANDARD 20（第 156-159 行），这与示例 CMakeLists.txt 中显式设置 CXX_STANDARD 20 相互呼应——使用 LibTorch 的项目必须使用 C++20 编译器。

5. GPU 依赖：当包为 CUDA 构建时（USE_CUDA=ON），模板还会追加 nvrtc 库、torch::nvtoolsext 目标及 c10_cuda 等 CUDA 相关库到 TORCH_LIBRARIES（第 122-138 行）。

另外，仓库顶层 CMakeLists.txt 中的安装规则会把上述 CMake 配置文件安装到 share/cmake/Caffe2 等目录，说明 LibTorch ZIP 包与 pip 轮子中的 CMake 配置都源自同一套模板，行为完全一致。

系统要求

为保证 LibTorch 安装与使用顺利，官方文档列出了以下硬性要求：

项目	要求	说明
GLIBC	2.29 或更新	针对 cxx11 ABI 版本的 LibTorch
GCC	9 或更新	针对 cxx11 ABI

这意味着在较老的发行版（如默认 GLIBC 低于 2.29 的系统）上运行 cxx11-ABI 的 LibTorch 可能直接失败；相应地，编译器版本过低也无法通过 LibTorch 头文件中的 C++20 语法编译。选型时请优先确认目标系统的这两个指标，并选择与你的程序 ABI 设置（-D_GLIBCXX_USE_CXX11_ABI）一致的 LibTorch 包。

Windows 开发者：Visual Studio 扩展替代方案

对不愿使用 CMake 的 Windows 开发者，官方文档推荐 LibTorch Project Template（Visual Studio Marketplace 上的 Visual Studio 扩展）。它可以自动完成 LibTorch 项目的全部设置，包括 debug 与 release 两种配置下的包含路径与链接选项，使用简便。唯一的前置条件就是：先从 PyTorch 官网下载好对应版本的 libtorch 发行版。

进阶：从源码构建 LibTorch

如果官方二进制发行版不满足需求（例如需要自定义编译选项、静态库、或最新 main 分支特性），可以直接从源码构建。当前仓库的版本号见 version.txt（main 分支处于 2.15 开发周期），仓库自带两种构建入口：

方式一：Python 脚本构建（见 docs/libtorch.rst）：

cd <pytorch_root>

# 使用独立目录构建，避免污染源码树
mkdir build_libtorch && cd build_libtorch

# 可能需要在此导出所需环境变量
python ../tools/build_libtorch.py

该脚本 tools/build_libtorch.py 的关键行为：优先使用 ninja 生成器（可通过 CMAKE_GENERATOR 覆盖）；根据环境变量决定构建类型——设置 DEBUG=1 得 Debug、REL_WITH_DEB_INFO=1 得 RelWithDebInfo，否则默认 Release（显式 CMAKE_BUILD_TYPE 优先级最高）；产物头文件与库最终安装到 <pytorch_root>/torch/{lib,include,share}——这与 pip 包的目录结构一致。AMD ROCm 用户需先运行 python tools/amd_build/build_amd.py。

方式二：直接使用 CMake：

mkdir pytorch-build
cd pytorch-build
cmake -DBUILD_SHARED_LIBS:BOOL=ON -DCMAKE_BUILD_TYPE:STRING=Release \
      -DPYTHON_EXECUTABLE:PATH=`which python3` \
      -DCMAKE_INSTALL_PREFIX:PATH=../pytorch-install \
      <pytorch_root>
cmake --build . --target install

补充要点：

• 设置 BUILD_SHARED_LIBS=OFF 可产出 libtorch.a 静态库而非 libtorch.so；
• 构建依赖 Python3 及其 PyYAML 等包，缺失会直接报 CMake 配置错误；
• 生成器可用 CMAKE_GENERATOR 指定，ninja 可用时脚本会自动选用。

遇到问题时的求助渠道

如果在安装或最小示例使用过程中遇到问题，官方文档建议通过 PyTorch 官方论坛（discuss.pytorch.org）或本仓库的 GitHub issues 反馈。排查时，可以先核对三类信息：CMAKE_PREFIX_PATH 是否指向了解压后的 LibTorch 根目录（而不是其子目录）、所选 LibTorch 包的 ABI/CUDA 变体是否与你的编译设置匹配、以及 GLIBC 与 GCC 版本是否满足上文系统要求。

小结

本文完整还原并深化了 installing.md 的全文脉络：从 LibTorch 发行版的定位与下载（CPU/GPU、shared/static、nightly/release 的选择），到最小 CMakeLists.txt 与 example-app.cpp 的逐行讲解，再到 configure/build/run 的完整命令序列与期望输出。在此之上，结合仓库内 cmake/TorchConfig.cmake.in、torch/utils/init.py、CMakeLists.txt、docs/libtorch.rst 与 tools/build_libtorch.py 的源码证据，解释了 find_package(Torch) 的前缀自定位、共享/静态两条链接路径、C++20 约束、pip 包与 LibTorch ZIP 的同构布局，以及从源码构建 libtorch 的两种入口。掌握这套流程后，你就能在任意 C++ 工程中稳定地集成 PyTorch 的张量与神经网络能力。