Qt 5 and Qt 6 compatibility

The semantics of the CMake API in Qt 5 and Qt 6 are largely compatible. However, up to Qt 5.14, all imported Qt library targets and commands contained the version number as part of the name. This makes writing CMake code that should work with both Qt 5 and Qt 6 somewhat cumbersome. Qt 5.15 therefore introduced versionless targets and commands to enable writing CMake code that is largely agnostic to the different Qt versions.

Versionless targets

In addition to the existing imported targets, Qt 5.15 introduced versionless targets. That is, to link against Qt Core one can both reference Qt6::Core, or Qt::Core:

 find_package(Qt6 COMPONENTS Core)
 if (NOT Qt6_FOUND)
     find_package(Qt5 5.15 REQUIRED COMPONENTS Core)
 endif()

 add_executable(helloworld
     ...
 )

 target_link_libraries(helloworld PRIVATE Qt::Core)

Above snippet first tries to find a Qt 6 installation. If that fails, it tries to find a Qt 5.15 package. Independent of whether Qt 6 or Qt 5 is used, we can use the imported Qt::Core target.

The versionless targets are defined by default. Set QT_NO_CREATE_VERSIONLESS_TARGETS before the first find_package() call to disable them.

Versionless commands

Since Qt 5.15, the Qt modules also provide versionless variants of their commands. You can for instance now use qt_add_translation to compile translation files, independent of whether you use Qt 5 or Qt 6.

Set QT_NO_CREATE_VERSIONLESS_FUNCTIONS before the first find_package() call to prevent the creation of versionless commands.

Mixing Qt 5 and Qt 6

There might be projects that need to load both Qt 5 and Qt 6 in one CMake context (though mixing Qt versions in one library or executable is not supported, so be careful there).

In such a setup the versionless targets and commands will be implicitly referring to the first Qt version that was found via find_package. Set the QT_DEFAULT_MAJOR_VERSION CMake variable before the first find_package call to make the version explicit.

Supporting older Qt 5 versions

If you need to support also Qt 5 versions older than Qt 5.15, you can do so by storing the current version in an CMake variable:

 find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)
 find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core)

 add_executable(helloworld
     ...
 )

 target_link_libraries(helloworld PRIVATE Qt${QT_VERSION_MAJOR}::Core)

Here we let find_package(<PackageName>...) try to find first Qt 6, and if that fails Qt 5, under the name QT. If either of them is found, find_package will succeed, and the CMake variable QT_VERSION_MAJOR will be defined to either 5 or 6.

We then do load the package for the determined Qt version again by creating the name Qt${QT_VERSION_MAJOR} on the fly. This is needed because CMAKE_AUTOMOC expects the package name to be either Qt5 or Qt6, and will print an error otherwise.

We can use the same pattern to also specify the name of the imported library. Before calling target_link_libraries, CMake will resolve Qt${QT_VERSION_MAJOR}::Widgets to either Qt5::Widgets or Qt6::Widgets.

Recommended practices

Use the versionless variants of the CMake commands where possible.

Use the versioned targets unless you have to support Qt 5 and Qt 6 in the same project.

If you have to use versionless targets, be aware of the Pitfalls when using versionless targets.

Use the versioned versions of the CMake commands and targets if you need to support Qt 5 versions older than Qt 5.15, or if you cannot control whether your CMake code is loaded in a context where QT_NO_CREATE_VERSIONLESS_FUNCTIONS or QT_NO_CREATE_VERSIONLESS_TARGETS might be defined. In this case you can still simplify your code by determining the actual command or target name through a variable.

Pitfalls when using versionless targets

Using the versionless targets has several downsides.

The versionless targets are ALIAS targets and lack the target properties of the versioned targets.

Projects must not export targets that expose the versionless targets. For example, a library that is consumed by another project must not export targets that link publicly against versionless targets. Otherwise, transitive dependencies might be broken, or the user of that library mixes Qt5 and Qt6 targets involuntarily.

Unicode support in Windows

In Qt 6, the UNICODE and _UNICODE compiler definitions are set by default for targets that link against Qt modules. This is in line with the qmake behavior, but it is a change compared to the CMake API behavior in Qt 5.

Call qt_disable_unicode_defines() on the target to not set the definitions.

 find_package(Qt6 COMPONENTS Core)

 add_executable(helloworld
     ...
 )

 qt_disable_unicode_defines(helloworld)