diff-gaussian-rasterization 二次编译复现记录——PyTorch 2.4.0+cu124 × CUDA 12.6 × FaceLift 项目环境

diff-gaussian-rasterization 二次编译复现记录——PyTorch 2.4.0+cu124 × CUDA 12.6 × FaceLift 项目环境

本文是 Windows 11 下编译 diff-gaussian-rasterization 完整踩坑记录——PyTorch 2.7.1+cu126 × CUDA Toolkit 13.1 × RTX 3090 的姊妹篇。记录在另一个全新 venv 环境中（FaceLift 项目），用不同的 PyTorch + CUDA 版本组合重新编译 diff-gaussian-rasterization 的完整过程。

核心发现：选对 CUDA Toolkit 版本比修改源码更重要。上次需要 patchcpp_extension.py绕过版本检查，这次只需switch-cuda 12.6一条命令即可编译通过——因为 PyTorch cu124 对 CUDA 12.6 只产生 Warning，不再报致命错误。

https://github.com/ashawkey/diff-gaussian-rasterization

https://github.com/weijielyu/FaceLift

一、与上次编译的关键差异对比

二、成功编译的完整环境清单

这是经过验证的可复现环境，缺一不可：

2.1 系统与硬件

• Windows 11
• NVIDIA RTX 3090（sm_86）
• 显卡驱动：595.02

2.2 编译工具链

• Visual Studio 2022 Professional v17.12.19
  • MSVC v14.42.34444（cl.exe for x64）
  • 必须在VS 2022 Developer Command Prompt中操作
  • Windows SDK 10.0.26100.0
• CUDA Toolkit 12.6（V12.6.85）
  • 通过switch-cuda.bat 12.6切换
  • 含内嵌 cuDNN 8.x
• ninja（通过pip install ninja，PyTorch cpp_extension 自动调用）

2.3 Python 环境

• Python 3.12.x（venv 虚拟环境）
• PyTorch 2.4.0+cu124
• setuptools（已含 bdist_wheel 支持）

2.4 源码依赖

• diff-gaussian-rasterization：graphdeco-inria/diff-gaussian-rasterization
• GLM 数学库：已放置于diff-gaussian-rasterization/third_party/glm/

GLM 的准备方法请参见上篇文章。本次直接复用了上次编译成功的目录（含 GLM），省去了重新配置的步骤。如果你是首次编译，必须先准备 GLM：

cd diff-gaussian-rasterization\third_party git clone https://github.com/g-truc/glm.git

三、编译全过程

3.1 第一次尝试：CUDA 13.1 → 失败

在 VS 2022 Developer Command Prompt 中，系统默认 CUDA 版本为 13.1：

set DISTUTILS_USE_SDK=1 set MSSdk=1 python setup.py bdist_wheel

立即报错：

RuntimeError: The detected CUDA version (13.1) mismatches the version that was used to compile PyTorch (12.4). Please make sure to use the same CUDA versions.

错误根因：PyTorch 2.4.0+cu124 编译时使用的是 CUDA 12.4，而系统默认 nvcc 是 13.1。cpp_extension.py中_check_cuda_version()检测到主版本号差异（13 vs 12），直接raise RuntimeError阻止编译。

3.2 CMD 中切换 CUDA 版本

这里正是我们刚开发的 CMD 版switch-cuda.bat发挥作用的地方。但在 VS Developer Command Prompt 中，doskey宏可能未加载（因为 VS 的启动脚本不走cmd-init.bat的 AutoRun），所以需要用全路径调用：

"D:\Program\switch-cuda.bat" 12.6

输出：

[OK] Switched to CUDA 12.6 CUDA : C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6 CUDA x64 : C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6\bin\x64 cuDNN : C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6\bin Cuda compilation tools, release 12.6, V12.6.85

切换后验证编译器就位：

where cl :: D:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Tools\MSVC\14.42.34433\bin\Hostx64\x64\cl.exe

3.3 清理旧的 build 目录

因为是从上次编译的目录复制过来的，build/目录里残留着上次环境（PyTorch 2.7.1+cu126）的编译产物，直接用会导致链接时符号不匹配。必须清理：

rd /s /q build rd /s /q dist rd /s /q diff_gaussian_rasterization.egg-info

3.4 第二次尝试：CUDA 12.6 → 成功

set DISTUTILS_USE_SDK=1 set MSSdk=1 python setup.py bdist_wheel

这次_check_cuda_version()检测到 CUDA 12.6 vs PyTorch cu124（12.4），只产生Warning而非致命错误：

UserWarning: The detected CUDA version (12.6) has a minor version mismatch with the version that was used to compile PyTorch (12.4). Most likely this shouldn't be a problem.

编译正常推进，5 个编译单元全部通过：

[1/5] nvcc ... forward.cu → forward.obj ✓（warning #177-D 无害） [2/5] nvcc ... backward.cu → backward.obj ✓（warning #177-D 无害） [3/5] cl ... ext.cpp → ext.obj ✓ [4/5] nvcc ... rasterizer_impl.cu → rasterizer_impl.obj ✓ [5/5] nvcc ... rasterize_points.cu → rasterize_points.obj ✓

链接阶段：

link.exe ... /OUT:_C.cp312-win_amd64.pyd 正在创建库 ... _C.cp312-win_amd64.lib 已完成代码的生成

最终产出 wheel：

creating 'dist\\diff_gaussian_rasterization-0.0.0-cp312-cp312-win_amd64.whl'

3.5 安装验证

安装

pip install dist\diff_gaussian_rasterization-0.0.0-cp312-cp312-win_amd64.whl --force-reinstall :: Successfully installed diff-gaussian-rasterization-0.0.0

验证

python -c "import diff_gaussian_rasterization; print('✅ 安装成功')"

四、PyTorch 版本检查机制详解

这次编译最关键的认知是理解cpp_extension.py中_check_cuda_version()的判断逻辑：

PyTorch cu版本 实际 nvcc 版本 主版本号差异 结果 ───────────── ────────────── ────────── ──────────── 12.4 13.1 13≠12 → 大 RuntimeError（致命） 12.4 12.6 12=12 → 小 UserWarning（可忽略） 12.6 13.1 13≠12 → 大 RuntimeError（致命） 12.6 12.6 12=12 → 无 无任何提示

规则总结：只要 nvcc 主版本号与 PyTorch 编译时的 CUDA 主版本号一致，就只会产生 Warning。这意味着：

• PyTorch cu124 → 用 CUDA 12.x 的任何小版本都行（12.4/12.6/12.8/12.9）
• PyTorch cu126 → 同上
• 但任何 12.x PyTorch 都不能直接用 CUDA 13.x 编译（除非 patch 源码）

这就是为什么上次（cu126 + CUDA 13.1）需要修改cpp_extension.py，而这次（cu124 + CUDA 12.6）完全不需要。

五、编译过程中的 Warning 说明

编译通过但产生了几个 Warning，均无害：

5.1 CUDA 小版本 Warning

UserWarning: The detected CUDA version (12.6) has a minor version mismatch with the version that was used to compile PyTorch (12.4).

无害。同一主版本号内的 CUDA Toolkit 二进制兼容。

5.2 TORCH_CUDA_ARCH_LIST 未设置

UserWarning: TORCH_CUDA_ARCH_LIST is not set, all archs for visible cards are included for compilation.

无害。PyTorch 自动检测到 RTX 3090 并使用compute_86,code=sm_86，编译产物只适用于 Ampere 架构（RTX 30 系列），但对我们来说这正是需要的。如果想加速编译或明确指定：

set TORCH_CUDA_ARCH_LIST=8.6

5.3 variable "p_proj" was declared but never referenced

auxiliary.h(151): warning #177-D: variable "p_proj" was declared but never referenced

无害。diff-gaussian-rasterization 原始代码中的未使用变量，不影响功能。

5.4 setup.py install is deprecated

SetuptoolsDeprecationWarning: setup.py install is deprecated.

无害。setuptools 的弃用提醒，不影响 wheel 生成。

5.5 Py_DEBUG is unset

RuntimeWarning: Config variable 'Py_DEBUG' is unset, Python ABI tag may be incorrect

无害。使用非调试版 Python 时的正常提示。

六、从复制目录编译的注意事项

如果你和我一样，把之前编译成功的 diff-gaussian-rasterization 目录复制到新项目使用，有几点必须注意：

6.1 必须清理 build 目录

旧的build/目录里的.obj和.pyd是在旧环境（不同的 PyTorch 版本、不同的 CUDA 版本）下编译的，符号表和 ABI 都可能不匹配。不清理直接编译可能：

• 链接失败（符号未定义）
• 编译成功但 import 时 crash

rd /s /q build dist diff_gaussian_rasterization.egg-info

6.2 GLM 可以直接复用

third_party/glm/是纯头文件数学库，不含编译产物，跨环境复用没有任何问题。

6.3 源码不需要修改

diff-gaussian-rasterization 的.cu/.cpp/.h源码是通用的，不需要为不同环境修改。所有适配工作都在编译环境（CUDA 版本、环境变量）层面完成。

七、PyTorch 离线安装技巧

由于网络原因，pip install torch==2.4.0 ... --index-url https://download.pytorch.org/whl/cu124可能超时失败。解决方法是先获取 wheel URL，用 IDM 等下载工具下载到本地，再本地安装：

:: 1. 先尝试 pip install，从报错或日志中获取 wheel 下载地址 pip install torch==2.4.0 --index-url https://download.pytorch.org/whl/cu124 -v :: 2. 用 IDM / aria2 等工具下载 torch wheel 到本地 :: （例如下载 torch-2.4.0+cu124-cp312-cp312-win_amd64.whl） :: 3. 本地安装 torch，其余依赖走 pip 在线 pip install 本地路径\torch-2.4.0+cu124-cp312-cp312-win_amd64.whl torchvision==0.19.0 torchaudio==2.4.0 --index-url https://download.pytorch.org/whl/cu124

安装后验证：

python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())" :: 2.4.0+cu124 12.4 True

八、一键编译脚本（CMD 版）

将编译步骤封装为 batch 脚本，方便日后复现：

@echo off chcp 65001 >nul 2>&1 setlocal REM === diff-gaussian-rasterization 编译脚本（CMD 版） === REM 前提：在 VS 2022 Developer Command Prompt 中运行 REM 前提：已安装好 Python venv + PyTorch REM 1. 切换 CUDA 版本（匹配 PyTorch 主版本号） call "D:\Program\switch-cuda.bat" 12.6 REM 2. 设置编译环境变量 set DISTUTILS_USE_SDK=1 set MSSdk=1 set TORCH_CUDA_ARCH_LIST=8.6 REM 3. 清理旧构建 if exist build rd /s /q build if exist dist rd /s /q dist if exist diff_gaussian_rasterization.egg-info rd /s /q diff_gaussian_rasterization.egg-info REM 4. 编译 python setup.py bdist_wheel REM 5. 安装 for %%f in (dist\*.whl) do pip install "%%f" --force-reinstall endlocal

九、完整决策树：应对不同 PyTorch × CUDA 组合

开始编译 diff-gaussian-rasterization │ ├─ 检查 PyTorch 的 CUDA 版本 → python -c "import torch; print(torch.version.cuda)" │ 得到 X.Y（如 12.4） │ ├─ 检查系统 nvcc 版本 → nvcc --version │ 得到 A.B（如 13.1） │ └─ X 和 A 的主版本号相同？ │ ├─ 是 (如 12.4 vs 12.6) → 直接编译，忽略 Warning │ └─ 否 (如 12.4 vs 13.1) → 两条路： │ ├─ 路线 A（推荐）：switch-cuda 切换到 12.x 版本 │ switch-cuda 12.6 → 再编译 │ └─ 路线 B：修改 cpp_extension.py 将 _check_cuda_version 中的 raise RuntimeError 改为 warnings.warn → 再编译 （详见上篇文章）

十、总结

系列文章索引：

• 1. Windows 多版本 CUDA + cuDNN 环境配置完全指南

• 2. Windows CMD 多版本 CUDA & cuDNN 一键切换管理方案

• 3. Windows 11 下编译 diff-gaussian-rasterization 完整踩坑记录（首次编译）

• 4. 本文：diff-gaussian-rasterization 二次编译复现记录（不同环境复现）

FaceLift 项目运行测试：