[Bug]: `--cpp_only` build fails to configure: BUILD_PYT=OFF leaves TORCH_INSTALL_PREFIX empty, and core headers include torch unconditionally

System Info

• Container: nvcr.io/nvidia/tensorrt-llm/devel:1.3.0rc26, the image docs/source/installation/build-from-source.md tells you to use
• Commit: 63d217f2 on main (version 1.3.0rc27)
• x86_64, 256 cores, no GPU visible to the build (not needed to reach the failure)
• CMake 4.0.3, CUDA 13.2, Python 3.12.3, PyTorch 2.12.0a0+5aff3928d8.nv26.05

Who can help?

No response

Information

• The official example scripts
• My own modified scripts

Tasks

• An officially supported task in the examples folder (such as GLUE/SQuAD, ...)
• My own task or dataset (give details below)

Reproduction

Start the documented container, then from the repository root:

python3 scripts/build_wheel.py --cpp_only -a 90-real

--cpp_only is documented:

docs/source/installation/build-from-source.md:87
| `--cpp_only` | Build only the C++ runtime library, without Python bindings |

Expected behavior

CMake configures and the C++ runtime library builds without Python bindings.

actual behavior

Configure fails immediately:

CMake Error at tensorrt_llm/runtime/utils/CMakeLists.txt:28 (find_library):
  Could not find TORCH_PYTHON_LIB using the following names: torch_python

-- Configuring incomplete, errors occurred!

libtorch_python.so is present in the container, at
/usr/local/lib/python3.12/dist-packages/torch/lib/libtorch_python.so. The search hint is
what is missing.

find_package(Torch REQUIRED) sits at cpp/CMakeLists.txt:582, inside the if(BUILD_PYT)
block opened at line 529. --cpp_only passes -DBUILD_PYT=OFF, so TORCH_INSTALL_PREFIX
is never set and CMAKE_PREFIX_PATH never receives the torch directory. Meanwhile
cpp/tensorrt_llm/runtime/CMakeLists.txt:99 adds add_subdirectory(utils) with no guard,
so the find_library above is always reached.

Three configure-time sites need torch when BUILD_PYT=OFF:

File	Line	Statement
cpp/tensorrt_llm/runtime/utils/CMakeLists.txt	28	find_library(TORCH_PYTHON_LIB torch_python REQUIRED HINTS ${TORCH_INSTALL_PREFIX}/lib)
cpp/tensorrt_llm/executor/cache_transmission/ucx_utils/CMakeLists.txt	6	find_package(Torch REQUIRED)
cpp/tensorrt_llm/batch_manager/CMakeLists.txt	105	find_library(TORCH_PYTHON_LIB torch_python REQUIRED HINTS ${TORCH_INSTALL_PREFIX}/lib)

Controls

Configuration	Result
--cpp_only -a 90-real	fails at runtime/utils/CMakeLists.txt:28
-a 90-real (default, BUILD_PYT=ON)	-- Configuring done (85.0s), build files written
--cpp_only plus -D TORCH_INSTALL_PREFIX=<torch dir>	passes line 28, fails at ucx_utils/CMakeLists.txt:6
--cpp_only plus -D TORCH_INSTALL_PREFIX=<torch dir> -D CMAKE_PREFIX_PATH=<torch dir>/share/cmake	-- Configuring done (70.8s), then the compile errors below

BUILD_PYT is the only variable that separates success from failure here.

Supplying the torch paths is not enough

With both paths supplied, configure succeeds and the compile then fails in three headers
that include torch or ATen without any BUILD_PYT guard:

cpp/include/tensorrt_llm/runtime/utils/pgUtils.h:24:10: fatal error:
    torch/csrc/distributed/c10d/ProcessGroup.hpp: No such file or directory
cpp/tensorrt_llm/common/ncclUtils.h:25:10: fatal error:
    ATen/cuda/CUDAContext.h: No such file or directory
cpp/tensorrt_llm/thop/thUtils.h:22:10: fatal error:
    ATen/cuda/CUDAContext.h: No such file or directory

These reach the C++-only build through core code:

• cpp/include/tensorrt_llm/batch_manager/cacheTransceiver.h:28 includes pgUtils.h, with
  no conditional compilation anywhere in that header.
• cpp/tensorrt_llm/common/ncclUtils.h:25 includes <ATen/cuda/CUDAContext.h> and
  <torch/extension.h> under #if ENABLE_MULTI_DEVICE, which is on by default and is
  independent of BUILD_PYT. common/ncclUtils.cpp and common/opUtils.cpp include it.
• cpp/tensorrt_llm/kernels/trtllmGenKernels/blockScaleMoe/runner.h includes
  thop/thUtils.h, so a thop header is compiled even though add_subdirectory(thop)
  is correctly guarded by BUILD_PYT at cpp/tensorrt_llm/CMakeLists.txt:293.

So the C++-only build now depends on torch and on libtorch_python.so, which is the
opposite of what the flag is documented to do.

How long this has been the case

Via the GitHub API, cpp/tensorrt_llm/runtime/utils/CMakeLists.txt and
cpp/include/tensorrt_llm/runtime/utils/pgUtils.h were both created on 2025-10-04 by
88ea2c4e ("[TRTLLM-7349][feat] Adding new orchestrator type -- ray", #7520). The
find_library(TORCH_PYTHON_LIB torch_python REQUIRED ...) line was present in that first
version, and add_subdirectory(utils) has been unguarded from that commit through today.

I have not built any intermediate commit, so I cannot name the first commit at which
--cpp_only stopped working. What I can say is that the two halves of the cause have
been in the tree in this shape for about eleven months, which suggests no CI job exercises
--cpp_only.

Possible directions

1. Discover Torch regardless of BUILD_PYT. This unblocks configure in three lines, but
   leaves the C++-only library depending on torch and torch_python.
2. Keep the C++-only build free of torch by guarding the pg_utils use in
   cacheTransceiver, the ATen include in common/ncclUtils.h, and the thUtils.h
   include in blockScaleMoe/runner.h.
3. If --cpp_only is no longer intended to work, remove it from build_wheel.py and from
   the flag table in the build documentation, so the failure is not silent.

I am glad to send a patch for whichever direction you prefer.

additional notes

I found this while trying to build with -D SANITIZE=address,undefined and
-D INDEX_RANGE_CHECK=ON. Neither option is involved: the failure reproduces with
--cpp_only alone and no extra CMake variables.

Start by reproducing python3 scripts/build_wheel.py --cpp_only -a 90-real, then read cpp/CMakeLists.txt, the three CMake files named in the report, and the listed headers that include Torch or ATen. Confirm which approach maintainers want for keeping BUILD_PYT=OFF independent of Torch. Done means the documented C++-only configuration and build complete without Python bindings or unconditional Torch dependencies.