Versions and policies

cmake_minimum_required(VERSION 4.4) is the first line of every CMake file, and the most misunderstood. This lesson explains exactly what that number does.

The version does two jobs

cmake_minimum_required(VERSION 4.4)

1. Minimum requirement. If the installed CMake is older than 4.4, it stops with an error.
2. Policy version. It tells CMake that this project expects the behavior of CMake 4.4. All behavior changes introduced up to 4.4 are turned on in their modern form.

The second job is the important one. As CMake evolves, a behavior sometimes needs to change. Each change gets a policy number (CMP####) with an OLD and a NEW behavior. cmake_minimum_required(VERSION 4.4) switches every policy up to 4.4 to NEW, the correct behavior, in one line.

Why

Without policies, upgrading CMake would silently change how old projects build. With them, you decide when a project moves to new behavior, by bumping the version number. That is the whole system, and it is why the first line matters.

The range syntax, VERSION 3.28...4.4

Projects often write:

cmake_minimum_required(VERSION 3.28...4.4)

Here:

• 3.28 is the true minimum. CMake refuses to run if the installed version is older. Nothing before the ... is ever “forbidden”.
• 4.4 (after ...) is only the policy version, meaning “I have tested this project with CMake up to 4.4, so turn on all NEW behaviors through 4.4”.

Note

The range does not forbid newer CMake. It only says “I have tested this project up to CMake 4.4”. Newer CMake still runs it, and policies through 4.4 stay NEW.

Which one should you write? Two honest answers:

• New project where you control the environment. cmake_minimum_required(VERSION 4.4). Simple, and the policy version matches your CMake.
• A library that others must consume. Pick a floor your users can meet, for example VERSION 3.28...4.4.

What breaks in CMake 4.x

Since CMake 4.0, the policy version must be 3.5 or newer. Anything older is an error, not a warning:

cmake_minimum_required(VERSION 3.4)   # error on CMake 4.x. Policy version too old.
cmake_minimum_required(VERSION 3.5)   # ok
cmake_minimum_required(VERSION 3.0...4.4)  # ok. The policy version is 4.4.

The check is on the policy version, the second number of the range. The OLD behaviors of the earliest policies (CMP0000 through CMP0065) were removed entirely from CMake 4.x. That is what “compatibility with CMake < 3.5 removed” means.

Pitfall

Old tutorials and old project templates start with cmake_minimum_required(VERSION 3.10) or lower. If a project you clone errors immediately on CMake 4.x, this is usually why. The fix is one line, and updating it is your decision. That is exactly how the policy system is designed to work.

When you see a policy warning

Sometimes a build prints something like:

CMake Warning (dev) at CMakeLists.txt:8 (add_library):
  Policy CMP0079 is not set: ...

It means a feature you used behaves differently in newer CMake, and you have not picked a side. Fix it by choosing the modern behavior explicitly, or better, by bumping your policy version so it happens automatically:

cmake_minimum_required(VERSION 4.4)          # fixes most policy warnings
# or, for one specific policy:
cmake_policy(SET CMP0079 NEW)

Tip

Two ways to set policies. cmake_minimum_required sets all of them up to a version at once, which is what you want. cmake_policy(SET CMP#### NEW) flips one at a time, which you rarely need. OLD is only a temporary bridge. OLD behaviors are deprecated and eventually removed, exactly like the pre-3.5 behaviors removed in 4.0.

Read the docs

• cmake_minimum_required
• cmake_policy
• Policies manual
• CMake 4.0 release notes