Repository navigation
docs: Read the Docs build fails since PyTorch 2.14 requires C++20 #6048
Description
Problem
The docs/readthedocs.org:deepmd check has failed on almost every build since 2026-09-28, including the latest build of master. The last green master build was on 2026-09-23 (#34710895, f7e7b9e65); the next master build, on 2026-09-29 (#34839820, 5b9fe0716), failed.
Cause
The docs environment installs .[docs,cpu,torch] from source (doc/requirements.txt), so Read the Docs compiles the PyTorch custom operators. torch is unpinned there and now resolves to PyTorch 2.14. PyTorch 2.14 raised its minimum C++ standard: torch/csrc/api/include/torch/all.h checks __cplusplus < 201703L in v2.13.0 and __cplusplus < 202002L in v2.14.0. deepmd-kit builds with C++17 (set_if_higher(CMAKE_CXX_STANDARD 17) for Torch_VERSION >= 2.1.0, source/CMakeLists.txt), so the build stops at the first source file that includes PyTorch:
FAILED: [code=1] op/pt/CMakeFiles/deepmd_op_pt.dir/comm.cc.o
.../torch/include/torch/csrc/api/include/torch/all.h:5:2: error: #error C++20 or later compatible compiler is required to use PyTorch.
error: Failed to build `deepmd-kit @ file:///home/docs/checkouts/readthedocs.org/user_builds/deepmd/checkouts/6025`
From build https://app.readthedocs.org/projects/deepmd/builds/34940025/ (#6025). The same error appears in the master build #34839820 and in the builds of #5955, #6023, #6040, #6041, #6008, #6043 and #5999 that I checked.
Impact
Every pull request whose docs are built after 2026-09-28 shows a red docs check, whatever it changes. The only green builds since then come from #5961, after its change to .readthedocs.yml (below).
docs/readthedocs.org:deepmd is not one of master's required status checks, so this does not block merging. It does mean the docs check no longer tells us whether a pull request broke the documentation.
Possible fixes
- Skip the custom operators in the docs build. docs(skills): add structured DPA4 workflow support #5961 does this in
5c509d5de:DP_ENABLE_PYTORCH=0in theuv pip install -r doc/requirements.txtstep of.readthedocs.yml. It was the only change between that PR's last failing build and its first passing one, and the docs do not run the operators. - Pin PyTorch below 2.14 for the docs build. A line in
doc/requirements.txtwould not be enough on its own: the build backend adds an unpinnedtorch>=2.1.0to the isolated build environment when PyTorch is not already installed (backend/find_pytorch.py), and that is the copy the operators are compiled against. SettingPYTORCH_VERSIONfor the install step, or installing a pinnedtorchbefore it, would cover both. - Build with C++20 when PyTorch is 2.14 or newer. This matters beyond the docs: anyone compiling deepmd-kit against PyTorch 2.14 will hit the same error, and the test workflows only pass because they pin PyTorch (
torch==2.11.0on CPU,2.10.0on GPU, in thepin_pytorch_*dependency groups).
Option 1 is the smallest change and is already written. Option 3 fixes the underlying incompatibility.
Activity
fix(pt): use C++20 with PyTorch 2.14+
docs: skip PyTorch operators in Read the Docs build
fix(pt): support PyTorch 2.14 C++20 builds (deepmodeling#6049)