skip to content

In CMake, what does cmake_minimum_required(VERSION 3.25...4.4) actually set, and what does CMake 4 do with a minimum below 3.5?

level: middleimportance: must knowfreq 55%

answer

  1. two numbers, two meanings
  2. the policy version
  3. NEW up to the max
  4. compatibility below 3.5 removed
  5. CMAKE_POLICY_VERSION_MINIMUM

basics

~20 s

It refuses CMake releases older than 3.25 and sets the policy version to 4.4, so every policy introduced up to 4.4 uses NEW behaviour. CMake 4 rejects a policy version below 3.5 with an error unless CMAKE_POLICY_VERSION_MINIMUM raises it.

solid answer

~40 s

`cmake_minimum_required(VERSION <min>...<policy_max>)` does two jobs. It stops with an error if the running CMake is older than `<min>`, and it sets the **policy version**: `<policy_max>` when given, otherwise `<min>`. Every policy introduced in that version or earlier is set to `NEW`; later policies stay unset, so they use their `OLD` behaviour and may warn. The range form (since 3.12) says: works with 3.25, tested and updated through 4.4; it does not forbid newer CMake. The call belongs at the top of the top-level `CMakeLists.txt`, before `project()`. CMake 4.0 removed compatibility with versions below 3.5: a policy version under 3.5 is a configure error, and since 3.31 one below 3.10 draws a deprecation warning. A user building an unmaintained project can pass `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` (since 4.0) to try anyway.

go deeper

for a junior

Know that cmake_minimum_required is the first line of the top-level CMakeLists.txt and that CMake refuses to run when it is older than the stated minimum.

for a middle

Explain the policy version: NEW for policies up to it, unset and OLD for later ones, and what the <min>...<policy_max> range changes.

for a senior

Fix projects that CMake 4 rejects for a minimum below 3.5, know when CMAKE_POLICY_VERSION_MINIMUM is acceptable, and raise policy_max deliberately with each CMake upgrade.

for a principal

Set the supported CMake range as a team policy, balancing users on older distributions against the cost of carrying OLD behaviours.

## Two numbers with different jobs `cmake_minimum_required(VERSION 3.25...4.4)` looks like a single requirement, but the two numbers mean different things: | Part | Meaning | Effect | |---|---|---| | `<min>` (`3.25`) | the oldest CMake that may process the project | an older CMake stops with an error; `CMAKE_MINIMUM_REQUIRED_VERSION` is set to it | | `<policy_max>` (`4.4`) | the newest CMake the project has been updated for | sets the **policy version** | The `...` is literal and the range form exists since CMake 3.12; older releases read the dots as version separators and ignore the second part. The `FATAL_ERROR` keyword is still accepted but ignored by every release since 2.6. ## Policies and the policy version CMake changes behaviour carefully. When a release fixes or tightens something, it introduces a **policy** named `CMP<NNNN>` with an `OLD` behaviour (the historical one) and a `NEW` behaviour. The `cmake-policies` manual describes policies as deprecation mechanisms, not feature toggles. The **policy version** decides which ones a project gets: 1. every policy introduced in the policy version or earlier is set to **`NEW`**; 2. every policy introduced later is left **unset**; an unset policy uses its `OLD` behaviour, and CMake may warn that it is not set; 3. a `CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable can give an unset policy a default from outside the project. So the second number is a promise about behaviour, not a ceiling on the tool. In the words of the documentation, `...<policy_max>` does not forbid later CMake versions; it records the newest version for which the project has been actively updated. ## What CMake 4 removed Old policies do not stay forever. The schedule documented in `cmake-policies` allows a warning about an `OLD` behaviour two years after the policy appears, and removal of the `OLD` behaviour in a later major version at least six years after. CMake 4.0 exercised that: - compatibility with CMake older than **3.5** is **removed**: a `cmake_minimum_required` or `cmake_policy(VERSION)` whose policy version is below 3.5 is an error; - since 3.31, a policy version below **3.10** draws a deprecation warning. Configuring a project that still says `cmake_minimum_required(VERSION 3.0)` with CMake 4.4 prints: ```plaintext CMake Error at CMakeLists.txt:1 (cmake_minimum_required): Compatibility with CMake < 3.5 has been removed from CMake. Update the VERSION argument <min> value. Or, use the <min>...<max> syntax to tell CMake that the project requires at least <min> but has been updated to work with policies introduced by <max> or earlier. Or, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to try configuring anyway. ``` `CMAKE_POLICY_VERSION_MINIMUM` (new in 4.0) raises the policy version from outside, so a user can build an unmaintained third-party project. The variable's documentation says projects should not set it themselves; the real fix is to update the project's call. ## Where the call goes - **First line of the top-level `CMakeLists.txt`**, before `project()`, so the policy settings are in force before any command whose behaviour they affect. Policy `CMP0000` exists because projects once omitted it. - **Not inside a `function()`**: some effects stay in the function scope while policy settings leak to the caller, and the documentation discourages it. - **Subdirectories** get their own entry on the policy stack, so a `cmake_minimum_required` there affects that directory and below, not the parent. ## Choosing the numbers - Set `<min>` to the oldest CMake you test and support, not to whatever was installed when the file was written. Raising it is a compatibility decision for your users. - Set `<policy_max>` to the newest CMake you have actually tested, and raise it when you upgrade, after fixing whatever the new `NEW` behaviours break. - Prefer the range over a lone `<min>`: a lone `3.25` leaves every policy from 3.26 onward unset, so newer CMake releases keep warning and apply old behaviours you did not ask for. - Check the effective setting of one policy with `cmake_policy(GET CMP0115 var)`, which yields `NEW`, `OLD` or an empty string when unset.

  • What is the practical difference between cmake_minimum_required(VERSION 3.25) and cmake_minimum_required(VERSION 3.25...4.4) when run by CMake 4.4?
    Both refuse CMake older than 3.25. The first sets the policy version to 3.25, so policies added in 3.26 through 4.4 stay unset, keep their OLD behaviour and may warn. The second sets the policy version to 4.4, so all of those policies use NEW behaviour.
  • Should a project set CMAKE_POLICY_VERSION_MINIMUM in its own CMakeLists.txt to silence the CMake 4 error?
    No. Its documentation says projects should not set it as a way to choose their own policy version; it is meant for a user building a project they cannot edit. A maintained project fixes the `cmake_minimum_required` call, ideally with a range.

  • The second number in VERSION 3.25...4.4 forbids running with CMake newer than 4.4
  • cmake_minimum_required only checks the CMake version and changes no behaviour
  • An unset policy uses its NEW behaviour automatically
  • cmake_minimum_required can go anywhere, even after project() and add_subdirectory()
  • CMake 4 still accepts cmake_minimum_required(VERSION 2.8) with only a warning

Assumes CMake 4.4; compatibility below 3.5 was removed in 4.0, below 3.10 is deprecated since 3.31, and CMAKE_POLICY_VERSION_MINIMUM exists since 4.0.