Linux 下编译 PyTorch 的关键注意事项
一 环境与工具链
- 使用受支持的 Python 版本（建议 ≥ 3.8），并在 conda/venv 中隔离环境，避免系统包冲突。
- 安装基础编译工具与构建链：build-essential/cmake/git 等；GPU 构建需提前准备 CUDA/cuDNN 并确认版本匹配。
- 发行版差异：
- Ubuntu/Debian：sudo apt install -y build-essential cmake git python3-dev python3-pip
- CentOS/RHEL：sudo yum groupinstall “Development Tools” -y && sudo yum install -y gcc-c++ cmake git python3-devel python3-pip
- 建议优先使用 CMake + Ninja 构建；若 conda 环境中 CMake 版本偏低，用 conda 升级后再构建。
二 获取源码与子模块
- 使用 git clone --recursive 拉取代码与子模块；网络不稳时，先获取主仓库，再分批更新子模块：
- git submodule sync
- git submodule update --init --recursive
- 切换版本前保持工作区干净，切换后再次同步子模块，避免第三方库不一致导致构建失败。
三 GPU 与依赖版本匹配
- 明确 CUDA 与 cuDNN 的兼容矩阵，确保头文件与库文件路径可被 CMake 正确找到；必要时设置环境变量（如 CUDA_HOME 等）。
- 老版本 PyTorch 对 cuDNN 版本文件位置敏感；例如 cuDNN 8 将版本信息移至 cudnn_version.h，若仅存在该文件而构建仍报“未找到/版本不符”，可将头文件软链到 CUDA 的 include 目录（示例：/usr/include/cudnn_version.h → /usr/local/cuda-11.8/include/）。
- 可选：安装与 CUDA 版本匹配的 Magma（如 conda install magma-cuda102），加速部分 GPU 线性代数运算。
四 构建配置与加速
- 设置 CMAKE_PREFIX_PATH，让构建系统找到 conda 环境中的库与头文件：
- export CMAKE_PREFIX_PATH=${CONDA_PREFIX:-“$(dirname $(which python))/…/”}
- 常用开关（按需精简功能以提速/规避依赖）：
- USE_DISTRIBUTED=0 USE_MKLDNN=0 BUILD_TEST=0 USE_FBGEMM=0 USE_NNPACK=0 USE_QNNPACK=0 USE_XNNPACK=0
- 指定目标 GPU 架构 减少编译负担与体积：
- TORCH_CUDA_ARCH_LIST=“7.5”（示例为 Turing 架构）
- 加速与稳定性：
- 启用 CCache 缓存加速重复构建；
- 控制并行任务数，避免 -j$(nproc) 导致 OOM 或 I/O 抖动（必要时保留少量核心给系统）。
五 常见错误与排查
- 编译器/标准库不兼容：
- 低版本 GCC 可能触发 ATen 等模块编译失败；可临时切换至合适版本（如 gcc-4.9/g+±4.9）。
- 运行期报 GLIBCXX_3.4.xx not found：升级/替换环境中的 libstdc++（如 conda install libgcc，或调整 LD_LIBRARY_PATH 指向含新版本 GLIBCXX 的库）。
- 构建产物冲突：源码根目录下存在 torch/ 目录时，Python 会优先导入本地包导致 ModuleNotFoundError: No module named ‘torch._C’；退出到上层目录再导入。
- 清理与重来：
- 变更配置或版本前执行：pip uninstall torch；python setup.py clean
- cuDNN 头文件/版本问题：确认 cudnn_version.h 位置与可见性，必要时软链至 CUDA include。
六 验证与后续
- 安装完成后在目标环境中验证：
- python -c “import torch; print(torch.version); print(‘CUDA 可用:’, torch.cuda.is_available())”
- 若需配套 torchvision，注意与已编译 PyTorch 版本严格对应；为避免 pip/conda 解析冲突，建议离线安装对应版本的 torchvision 且不加额外依赖。
