scikit-build "CMake Error ... could NOT find Python" in CI

scikit-build drives CMake, which runs find_package(Python ... Development.Module). If the Python development component (headers, library) is not discoverable, CMake fails with "Could NOT find Python" and the wheel build stops.

What this error means

The build fails inside CMake configure with "CMake Error ... Could NOT find Python (missing: Python_INCLUDE_DIRS Development.Module)" or a similar find_package failure.

CMake Error at .../FindPython.cmake:
  Could NOT find Python (missing: Python_INCLUDE_DIRS Development.Module)
  (found version "3.11.4")

Common causes

Development.Module component not available

find_package can locate the interpreter but not the headers/lib needed for the Development.Module component, so it reports Python as not found.

Dev headers missing on the runner

Without python3-dev, CMake cannot resolve Python_INCLUDE_DIRS, which is exactly what Development.Module needs.

How to fix it

Install the Python development headers

1. Install python3-dev/python3-devel on the runner.
2. Ensure the active interpreter matches the installed headers.
3. Re-run the scikit-build wheel build.

- run: sudo apt-get update && sudo apt-get install -y python3-dev
- run: pip wheel . -w dist

Let scikit-build-core find the active interpreter

Use setup-python so the headers and interpreter that scikit-build-core targets are consistent.

- uses: actions/setup-python@v5
  with: { python-version: '3.11' }

How to prevent it

• Install dev headers for the interpreter scikit-build targets.
• Use setup-python so CMake finds a consistent Python.
• Run the CMake configure step in CI to catch find_package errors.

Related guides