Porting to Qt 6

There are many changes to Qt from the previous version, Qt 5, to Qt 6. Before upgrading to Qt 6, make sure that your Qt 5 application is updated to Qt 5.15. The latest Qt 5 version has the least amount of changes when porting to Qt 6. However, APIs marked as deprecated or obsolete in Qt 5.15 may have been removed in Qt 6.

Here are things you should check if you are porting your Qt 5 applications into Qt 6.

Disable use of C++ API deprecated in Qt 5.15

Usage of API deprecated in Qt will typically show up in the form of a compiler warning. You can also make the use an error by defining the QT_DISABLE_DEPRECATED_BEFORE C++ macro in your build system. To disable any API deprecated in 5.15 or older Qt versions, define the macro to 0x050F00, which is '5.15.0' encoded as a hexadecimal number.

For example, in a qmake project file, define the macro with:

DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0x050F00

In CMake, you can use add_compile_definitions:

add_compile_definitions(QT_DISABLE_DEPRECATED_BEFORE=0x050F00)

Check the Changes to the Modules

A goal for the Qt 6 release is to maintain a streamlined framework which means the removal of some Qt 5 modules in Qt 6. In some cases, APIs from a deprecated module are available in another module. In future Qt 6 releases, new or previous modules may be added.

Test for Graphical Regressions

QML applications have a new graphical backend, which you should test for regressions. OpenGL is no longer guaranteed as default on target platforms and you should check that your graphics code is still creating the same effects you want.

It is still possible to use OpenGL calls in Qt applications, but the OpenGL APIs are moved to the Qt OpenGL module. The graphical backend for Qt Widgets applications are unchanged from Qt 5.

High-DPI

Qt 6 supports high-DPI displays on all platforms, and will automatically account for the display resolution when using higher level APIs such as Qt Widgets or Qt Quick. Applications only need to provide high-resolution assets, such as images and icons. The feature is always enabled.

Qt 6 changes the default scale factor rounding policy from Qt::HighDpiScaleFactorRoundingPolicy::Round to Qt::HighDpiScaleFactorRoundingPolicy::PassThrough in order to track operating system DPI settings accurately. Applications that use Qt Widgets may encounter graphical glitches at non-integer scale factors, for example on Windows with a display configured for 175%. In that case, set the rounding policy to Round to restore Qt 5 behavior.

See High DPI for more details.

Use the Platform Integration APIs

There is better integration with the native APIs on target platforms in Qt 6. You can use platform integration APIs to implement native behavior that is not provided by Qt. For Qt 6, check for any updates to your application's target platform.

Use Porting Tool

A Clazy-based tool is available to facilate porting from Qt 5 to Qt 6: Porting C++ Applications to Qt 6 using Clazy checks.

Further Reading

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.