CMake cannot found Python Development.Module for Android with Python 3.14 (3.13 works fine)

[XuehaiPan]

Description

I'm trying to build wheels in GitHub Action for Android with Python 3.14 (newly supported by cibuildhwheel 3.2). The CMake program fails to find Python modules with cp314-android while cp313-android works fine.

The CMake error log (see https://github.com/metaopt/optree/actions/runs/18182914758/job/51772310290?pr=242):

  CMake Error at /tmp/cibw-run-e6ejroha/cp314-android_arm64_v8a/venv/lib/python3.14/site-packages/cmake/data/share/cmake-4.1/Modules/FindPackageHandleStandardArgs.cmake:227 (message):
    Could NOT find Python (missing: Development.Module) (found suitable version
    "3.14.0", minimum required is "3.8")
  
        Reason given by package: 
            Development: Cannot find the directory "/tmp/cibw-run-e6ejroha/cp314-android_arm64_v8a/venv/include/python3.14"

  Call Stack (most recent call first):
    /usr/local/share/cmake-3.31/Modules/FindPackageHandleStandardArgs.cmake:603 (_FPHSA_FAILURE_MESSAGE)
    /usr/local/share/cmake-3.31/Modules/FindPython/Support.cmake:4002 (find_package_handle_standard_args)
    /usr/local/share/cmake-3.31/Modules/FindPython.cmake:631 (include)
    /tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/lib/python3.14/site-packages/pybind11/share/cmake/pybind11/pybind11NewTools.cmake:54 (find_package)
    /tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/lib/python3.14/site-packages/pybind11/share/cmake/pybind11/pybind11Common.cmake:204 (include)
    /tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/lib/python3.14/site-packages/pybind11/share/cmake/pybind11/pybind11Config.cmake:257 (include)
    CMakeLists.txt:261 (find_package)

Note that I have tried both CMake 3.31 in the build container and the latest CMake 4.x from PyPI. Either is failed with the above error.

Build log

https://github.com/metaopt/optree/actions/runs/18182914758/job/51772310290?pr=242

CI config

https://github.com/metaopt/optree/pull/242/files#diff-5c3fa597431eda03ac3339ae6bf7f05e1a50d6fc7333679ec38e21b337cb6721R210-R212

[XuehaiPan]

[Moved from python/cpython#139758]

I found the above directory (i.e., sysconfig.get_path('platinclude')) does not exist in the venv.

The build log diffs between Python 3.13 and Python 3.14 on Android:

Python 3.13: https://github.com/metaopt/optree/actions/runs/18335313182/job/52218210396?pr=242#step:11:577

Python executable: /tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/venv/bin/python (3.13.7 (main, Sep 18 2025, 19:47:49) [Clang 20.1.4 ])
Python platform: android-24-arm64_v8a (android-24-arm64_v8a)
Python sysconfig: {
    'ABIFLAGS': '',
    'EXT_SUFFIX': '.cpython-313-aarch64-linux-android.so',
    'INCLUDEDIR': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/python/prefix/include',
    'INCLUDEPY': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/python/prefix/include/python3.13',
    'LIBDEST': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/python/prefix/lib/python3.13',
    'LIBDIR': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/python/prefix/lib',
    'LIBPYTHON': '-L. -lpython3.13',
    'LIBRARY_DEPS': 'libpython3.13.so libpython3.so',
    'LIBRARY': 'libpython3.13.a',
    'LIBS': '-ldl  -llog',
    'SOABI': 'cpython-313-aarch64-linux-android',
}
Python paths: {
    'stdlib': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/python/prefix/lib/python3.13',
    'platstdlib': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/venv/lib/python3.13',
    'purelib': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/venv/lib/python3.13/site-packages',
    'platlib': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/venv/lib/python3.13/site-packages',
    'include': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/python/prefix/include/python3.13',
    'platinclude': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/python/prefix/include/python3.13',
    'scripts': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/venv/bin',
    'data': '/tmp/cibw-run-sntlw_f7/cp313-android_arm64_v8a/venv',
}

Python 3.14: https://github.com/metaopt/optree/actions/runs/18335313182/job/52218210389?pr=242#step:11:577

Python executable: /tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/bin/python (3.14.0rc3 (main, Sep 18 2025, 19:47:22) [Clang 20.1.4 ])
Python platform: android-24-arm64_v8a (android-24-arm64_v8a)
Python sysconfig: {
    'ABIFLAGS': '',
    'EXT_SUFFIX': '.cpython-314-aarch64-linux-android.so',
    'INCLUDEDIR': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/python/prefix/include',
    'INCLUDEPY': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/python/prefix/include/python3.14',
    'LIBDEST': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/python/prefix/lib/python3.14',
    'LIBDIR': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/python/prefix/lib',
    'LIBPYTHON': '-L. -lpython3.14',
    'LIBRARY_DEPS': 'libpython3.14.so libpython3.so',
    'LIBRARY': 'libpython3.14.a',
    'LIBS': '-ldl  -llog',
    'SOABI': 'cpython-314-aarch64-linux-android',
}
Python paths: {
    'stdlib': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/lib/python3.14',
    'platstdlib': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/lib/python3.14',
    'purelib': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/lib/python3.14/site-packages',
    'platlib': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/lib/python3.14/site-packages',
    'include': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/include/python3.14',
    'platinclude': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/include/python3.14',
    'scripts': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv/bin',
    'data': '/tmp/cibw-run-bewfqrm_/cp314-android_arm64_v8a/venv',
}

[XuehaiPan]

I found a workaround to make CMake find the Python module. Since the extension instance has an attribute ext.include_dirs. I pass it to CMake:

cmake_args += [
    f'-DPython_EXECUTABLE={sys.executable}',
    f'-DPython_INCLUDE_DIR={sysconfig.get_path("platinclude")}',
]
if self.include_dirs:
    cmake_args += [f'-DPython_EXTRA_INCLUDE_DIRS={";".join(self.include_dirs)}']

Then I iteratively search for Python.h in those directories to find a correct include where ${Python_INCLUDE_DIR}/Python.h exists.

message(STATUS "Detected Python include directory: \"${Python_INCLUDE_DIR}\"")  # is sysconfig.get_path('platinclude')
if (NOT EXISTS "${Python_INCLUDE_DIR}/Python.h")
    message(WARNING "Python.h not found in \"${Python_INCLUDE_DIR}\"")
    if (DEFINED Python_EXTRA_INCLUDE_DIRS)
        message(STATUS "Looking for Python.h in Python_EXTRA_INCLUDE_DIRS: "
                        "\"${Python_EXTRA_INCLUDE_DIRS}\"")
        foreach(Python_EXTRA_INCLUDE_DIR IN LISTS Python_EXTRA_INCLUDE_DIRS)
            if (EXISTS "${Python_EXTRA_INCLUDE_DIR}/Python.h")
                set(Python_INCLUDE_DIR "${Python_EXTRA_INCLUDE_DIR}")
                message(STATUS "Detected Python.h in \"${Python_INCLUDE_DIR}\"")
                break()
            endif()
        endforeach()
        if (NOT EXISTS "${Python_INCLUDE_DIR}/Python.h")
            message(WARNING "Python.h not found in Python_EXTRA_INCLUDE_DIRS")
        endif()
    endif()
endif()
include_directories("${Python_INCLUDE_DIR}")

• Patch for CMakeLists.txt: https://github.com/metaopt/optree/pull/242/files#diff-1e7de1ae2d059d21e1dd75d5812d5a34b0222cef273b7c3a2af62eb747f9d20aR208-R224
• A successful build run: https://github.com/metaopt/optree/actions/runs/18442627733/job/52545070358?pr=242#step:11:808

Note that sysconfig.get_path('platinclude') is still giving a wrong path for Python 3.14 on Android.