Skip to content

docs: Read the Docs build fails since PyTorch 2.14 requires C++20 #6048

Closed

Description

@iProzd

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

  1. Skip the custom operators in the docs build. docs(skills): add structured DPA4 workflow support #5961 does this in 5c509d5de: DP_ENABLE_PYTORCH=0 in the uv pip install -r doc/requirements.txt step 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.
  2. Pin PyTorch below 2.14 for the docs build. A line in doc/requirements.txt would not be enough on its own: the build backend adds an unpinned torch>=2.1.0 to the isolated build environment when PyTorch is not already installed (backend/find_pytorch.py), and that is the copy the operators are compiled against. Setting PYTORCH_VERSION for the install step, or installing a pinned torch before it, would cover both.
  3. 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.0 on CPU, 2.10.0 on GPU, in the pin_pytorch_* dependency groups).

Option 1 is the smallest change and is already written. Option 3 fixes the underlying incompatibility.

Activity

  1. added 2 commits that reference this issue on Oct 6, 2026
    a99523f
    211985a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions