# Where to use \`cmake\_minimum\_required\`?

**URL:** <https://discourse.cmake.org/t/where-to-use-cmake-minimum-required/11237>\
**Category:** Code\
**Created:** [July 13, 2024, 9:09am UTC](https://discourse.cmake.org/t/where-to-use-cmake-minimum-required/11237 "2024-07-13T09:09:25Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![Mateusz\_Pusz](https://discourse.cmake.org/user_avatar/discourse.cmake.org/mateusz_pusz/32/4760_2.png) [@Mateusz\_Pusz](https://discourse.cmake.org/u/Mateusz_Pusz)\
**Post date:** [July 13, 2024, 9:09am UTC](https://discourse.cmake.org/t/where-to-use-cmake-minimum-required/11237/1 "2024-07-13T09:09:25Z")

</div>

I would like to ask for a recommendation on how `cmake_minimum_required` should be used?

Until now, I have been putting `cmake_minimum_required` in all the CMake scripts (not only top-level ones) to advertise the minimum version needed for this particular file/script. It is useful when we want to reuse the same scripts in different projects.

However, one of my users raised this issue: [Inconsistent cmake\_minimum\_required · Issue #592 · mpusz/mp-units · GitHub](https://github.com/mpusz/mp-units/issues/592), claiming that is not the correct approach, and his rationale seems strong. In this particular case `CMP0074` policy was not used for some dependencies.

What do you think about this?

---

<div class="post-metadata">

**Author:** ![hsattler](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/h/59ef9b/32.png) [@hsattler](https://discourse.cmake.org/u/hsattler)\
**Post date:** [July 13, 2024, 10:48am UTC](https://discourse.cmake.org/t/where-to-use-cmake-minimum-required/11237/2 "2024-07-13T10:48:19Z")

</div>

I find your usage is not wrong. It states what that specific code was tested with. And yes, that may mean that newer features are unavailable.

It makes sense to update them from time to time anyway, maybe using a version range. 3.5 is quite old.

Within a single project, I would only use it on the top-level script though.

---

<div class="post-metadata">

**Author:** ![craig.scott](https://discourse.cmake.org/user_avatar/discourse.cmake.org/craig.scott/32/20_2.png) [@craig.scott](https://discourse.cmake.org/u/craig.scott)\
**Post date:** [July 13, 2024, 10:05pm UTC](https://discourse.cmake.org/t/where-to-use-cmake-minimum-required/11237/3 "2024-07-13T22:05:45Z")

</div>

I would generally put `cmake_minimum_required()` at the top of any file that might be used on its own, and not usually anywhere else. That means the top level `CMakeLists.txt` needs it, but the `CMakeLists.txt` files in subdirectories usually wouldn’t need it. If your project provides CMake module files that it installs for other projects to use, or that other projects may use directly if consuming yours via FetchContent, those module files should also have their own `cmake_minimum_required()` calls at their top. If they don’t, they will be at the mercy of whatever policy settings the consuming project uses.

Outside of the above cases, I’d generally recommend against putting otherwise unnecessary `cmake_minimum_required()` calls in files that already have their minimum CMake version and policy settings robustly controlled by a parent. Putting them in subdirectories’ `CMakeLists.txt` file invites inconsistent settings and can hamper efforts by other projects that consume yours (e.g. via FetchContent). I’ve seen this in some projects, which becomes more of an issue when CMake raises the minimum CMake version at which it issues deprecation warnings (this happens periodically).

Do note that if you make a CMake module available initially without having `cmake_minimum_required()` at the top to control its policy settings, it may be challenging to introduce it later. Doing so make be a breaking change for projects. We’ve faced this problem with CMake’s own module files on multiple occasions. So maybe err on the side of if a CMake module file might be made public at some point, put a `cmake_mimum_required()` in there. The cost is a maintenance one where you’ll have more files you need to keep in sync when you want to raise the minimum version (or as @hsattler mentions, raise the maximum if you use a version range, which is also a good idea).