Qt for Windows - Requirements

This page describes the required libraries and environment for Qt for Windows.

Libraries

The following third-party libraries may be used when running Qt applications on Windows.

  • OpenSSL Toolkit: Qt can make use of OpenSSL to support Secure Socket Layer (SSL) communication.
  • ICU: Qt can make use of the ICU library for enhanced UNICODE and Globalization support (see QTextCodec, QCollator::setNumericMode()).

    At compile time, the include and lib folders of the ICU installation must be appended to the INCLUDE and LIB environment variables. At run-time, the ICU DLLs need to be found by copying the DLLs to the application folder or by adding the bin folder of the ICU installation to the PATH environment variable.

SSL

Support for Secure Sockets Layer (SSL) communication is provided by the OpenSSL Toolkit, which must be obtained separately. Download the latest version of the toolkit that is supported by Qt.

Qt can be configured to use OpenSSL in three ways:

  • Qt Network loads OpenSSL libraries (DDLs) when first needed, at runtime. If not found, the application continues to run, but fails to handle SSL communication.

    All official Qt binary builds use this configuration.

    The OpenSSL libraries are looked up first in the directory of the executable, then in the Windows System directory (usually C:\Windows\system32), and finally in all directories listed in the PATH environment variable.

  • Qt Network links against the OpenSSL libraries. If they cannot be found at load time, the application fails to start.
  • Qt Network compiles against a static version of the OpenSSL libs, and OpenSSL becomes part of the Qt5Network library.

If you compile Qt yourself, you can configure how Qt uses OpenSSL by setting either the -openssl / -openssl-runtime or -openssl-linked configure flags.

If OpenSSL is not found in the normal compiler include and library directories, you can set either the OPENSSL_PREFIX, or OPENSSL_INCDIR and OPENSSL_LIBDIR configure arguments. If OPENSSL_PREFIX is set, OPENSSL_INCDIR defaults to OPENSSL_PREFIX/include and OPENSSL_LIBDIR to OPENSSL_PREFIX/lib.

The actual libraries to link to can be tweaked by setting the OPENSSL_LIBS, OPENSSL_LIBS_DEBUG, and OPENSSL_LIBS_RELEASE configure arguments.

  • To load OpenSSL at runtime, set the -openssl-runtime configure argument. Qt will try to find openssl/ssl.h and openssl/opensslv.h in the default include path of the compiler. You can specify an additional include directory by setting OPENSSL_INCDIR.

    For example:

     configure -openssl-runtime OPENSSL_INCDIR="C:\Program Files\OpenSSL-Win64\include"
    
  • To link Qt Network against OpenSSL libraries, set the -openssl-linked configure argument. Use the OPENSSL_PREFIX variable to let Qt correctly locate and build against your OpenSSL installation:

    For example:

     configure -openssl-linked OPENSSL_PREFIX="C:\Program Files\OpenSSL-Win64"
    
  • To link Qt Network against a static version of the OpenSSL libs, set the -openssl-linked argument, and set OPENSSL_PREFIX, or OPENSSL_INCDIR and OPENSSL_LIBDIR. In addition, you probably need to set the OPENSSL_LIBS, OPENSSL_LIBS_DEBUG, OPENSSL_LIBS_RELEASE configure arguments to let Qt correctly link against your static build of the OpenSSL libraries.

    For example:

     set OPENSSL_DIR=C:\Program Files\OpenSSL-Win64
     configure -openssl-linked OPENSSL_INCDIR="%OPENSSL_DIR%\include" OPENSSL_LIBDIR="%OPENSSL_DIR%\lib\VC\static" OPENSSL_LIBS="-lWs2_32 -lGdi32 -lAdvapi32 -lCrypt32 -lUser32" OPENSSL_LIBS_DEBUG="-llibssl64MDd -llibcrypto64MDd" OPENSSL_LIBS_RELEASE="-llibssl64MD -llibcrypto64MD"
    

See Secure Sockets Layer (SSL) Classes for further instructions on Qt with SSL support.

ICU

From Qt 5.3 and onwards, configure does not link Qt Core against ICU libraries anymore by default. This reduces the size of a self-contained application package considerably.

Letting Qt Core utilize the ICU libraries however has following advantages:

To explicitly enable the use of ICU in Qt Core, pass -icu to configure:

 configure -icu

Graphics Drivers

For Qt Quick 2 to work, a graphics driver that provides Direct 3D 11.1, Vulkan 1.0, or OpenGL 2.1 or higher is required. As of Qt 6, the default for Qt Quick on Windows is Direct3D 11. This is different from Qt 5, where the default was OpenGL, either directly, or through ANGLE, an OpenGL to Direct3D translator. ANGLE is no longer shipped with Qt in Qt 6.

To force using Direct3D's software rasterizer (WARP), set the environment variable QSG_RHI_PREFER_SOFTWARE_RENDERER to 1.

To request using Vulkan or OpenGL, both of which require a Vulkan or OpenGL driver to be installed, set the environment variable QSG_RHI_BACKEND to vulkan or opengl, or use the equivalent C++ API in main().

While not the default for Qt Quick, OpenGL is still commonly used in many Qt applications, for example in QWidget-based applications building on QOpenGLWindow or QOpenGLWidget. The following sections cover some OpenGL specifics of a Qt build.

Dynamically Loading OpenGL

Qt supports choosing and loading the OpenGL implementation at runtime. This mode is the default, and can be explicitly requested by passing -opengl dynamic to the configure script.

 configure -opengl dynamic

This configuration is the most flexible because no dependencies or assumptions are hardcoded about the OpenGL implementation during build time. It allows robust application deployment. When a given environment fails to provide a proper OpenGL 2.0 implementation, it will fall back automatically to load an alternative to opengl32.dll, the default name of which is opengl32sw.dll. The pre-built Qt packages ship a build of Mesa llvmpipe, a software rasterizer implementation of OpenGL, under that name.

When configured with -opengl dynamic, neither Qt nor the applications built using qmake or CMake will link to opengl32.lib. Instead, the library is chosen and loaded at runtime. By default, Qt will determine whether the system's opengl32.dll provides OpenGL 2 functions. If these are present, opengl32.dll is used, otherwise it attempts to load opengl32sw.dll. See below for details.

The loading mechanism can be configured through the QT_OPENGL environment variable and the following application attributes:

  • Qt::AA_UseDesktopOpenGL Equivalent to setting QT_OPENGL to desktop.
  • Qt::AA_UseOpenGLES Has no effect in Qt 6.
  • Qt::AA_UseSoftwareOpenGL Equivalent to setting QT_OPENGL to software.

When a certain configuration is requested explicitly, no checks are done at application startup, that is, the system-provided opengl32.dll will not be examined.

The dynamic loading has a significant impact on applications that contain native OpenGL calls: they may fail to link since opengl32.lib is not automatically specified to the linker. Instead, applications are expected to use the OpenGL functions via the QOpenGLFunctions class. Thus the direct dependency on the OpenGL library is removed and all calls will be routed during runtime to the implementation chosen by Qt. Alternatively, applications are free to make direct OpenGL function calls if they add opengl32.lib to their .pro project files: LIBS += opengl32.lib (Visual Studio) or LIBS += -lopengl32 (MinGW). The result is, from the application's perspective, equivalent to the -opengl desktop build configuration of Qt.

Qt::AA_UseSoftwareOpenGL is special in the sense that it will try to load an OpenGL implementation with a non-standard name. The default name is opengl32sw.dll. This allows shipping a software-only OpenGL implementation, for example a build of Mesa with llvmpipe, under this name. If necessary, the filename can be overridden by setting the QT_OPENGL_DLL environment variable.

It is possible to provide a JSON-format configuration file specifying which OpenGL implementation to use depending on the graphics card and driver version. The location is given by the environment variable QT_OPENGL_BUGLIST. Relative paths are resolved using QLibraryInfo::SettingsPath or QStandardPaths::ConfigLocation. The file utilizes the format of the driver bug list used in The Chromium Projects. It consists of a list of entries each of which specifies a set of conditions and a list of feature keywords. Typically, device id and vendor id are used to match a specific graphics card. They can be found in the output of the qtdiag or dxdiag tool.

The following feature keywords are relevant for choosing the OpenGL implementation:

Note: In Qt 6, the legacy ANGLE related keywords (disable_angle, disable_d3d11, disable_d3d9) are accepted, but have no effect.

  • disable_desktopgl - Disables OpenGL. This ensures that Qt does not attempt to use regular OpenGL (opengl32.dll), and that it starts with ANGLE right away. This is useful to prevent bad OpenGL drivers from crashing the application.
  • disable_rotation - Forces the application to run in landscape orientation always. It has no effect when using a software OpenGL implementation. This is intended for drivers that have issues with rotation. This feature keyword was introduced in Qt 5.6.
  • disable_program_cache - Disable storing shader program binaries on disk. This feature keyword was introduced in Qt 5.12.

A sample file looks like:

 {
 "entries": [
 {
   "id": 1,
   "description": "Disable D3D11 on older nVidia drivers",
   "os": {
     "type": "win"
   },
   "vendor_id": "0x10de",
   "device_id": ["0x0DE9"],
   "driver_version": {
     "op": "<=",
     "value": "8.17.12.6973"
   },
   "features": [
     "disable_d3d11"
   ]
 },
 ...

When QT_OPENGL_BUGLIST is not specified, a built-in list will be used. This typically includes some older, less-capable graphics cards with disable_desktopgl set, in order to prevent Qt from using their unstable desktop OpenGL implementations and instead fall back to attempting to load the software-based alternative library right away.

In practice the most common combinations are expected to be the following:

  • disable_desktopgl - In case the system provides OpenGL 2.0 or newer, but the driver is known to be unstable and prone to crash.
  • disable_desktopgl, disable_angle - When no accelerated path is desired. This ensures that the only option Qt tries is the sofware rasterizer (opengl32sw.dll). Can be useful in virtual machines and applications that are deployed on a wide range of old systems.

The supported keys for matching a given card or driver are the following. Note that some of these are specific to Qt.

  • os.type - Operating system: win, linux, macosx, android
  • os.version - Kernel version
  • os.release - Specifies a list of operating system releases on Windows: xp, vista, 7, 8, 8.1, 10.
  • vendor_id - Vendor from the adapter identifier
  • device_id - List of PCI device IDs.
  • driver_version - Driver version from the adapter identifier
  • driver_description - Matches when the value is a substring of the driver description from the adapter identifier
  • gl_vendor - Matches when the value is a substring of the GL_VENDOR string

To disable all blacklisting, set the environment variable QT_NO_OPENGL_BUGLIST to any value. This will skip reading any configuration files, and instead will assume that nothing is disabled, regardless of the driver or OS.

Note: While not typically needed, QT_NO_OPENGL_BUGLIST can become relevant in certain virtualized environments, with multiple, possibly virtual, graphics adapters present. If the logs from categories like qt.qpa.gl indicate that the detection of the driver and display adapter leads to incorrectly disabling OpenGL, it is then recommended to set this environment variable in order to enable the application to run normally. This environment variable was introduced in Qt 5.15.

Direct dependency to opengl32.dll

An alternative to the default dynamic OpenGL builds is to depend directly on opengl32.dll. For this mode, pass pass the command line options -opengl desktop to the configure script.

 configure -opengl desktop

Note: Using EGL and OpenGL ES is not supported on Windows. In Qt 6, OpenGL on Windows always implies using WGL as the windowing system interface.

In such Qt builds, many Qt shared libraries, and also Qt applications will have a dependency to opengl32.dll, and therefore using an alternative library is not possible.

Building from Source

These tools are not needed to run Qt applications, but they are required for building Qt from source.

  • ActivePerl - Install a recent version of ActivePerl (download page) and add the installation location to your PATH.
  • Python - Install Python from the here and add the installation location to your PATH.

Note: Please make sure that the perl executable from ActivePerl is found in the path before the perl executable provided by msysgit, since the latter is outdated.

For instructions for building the Qt source, read the Qt for Windows - Building from Source page.

Compilers

Visual Studio

Qt can be built with Visual Studio 2015 (Update 2), Visual Studio 2017, Visual Studio 2019 and Build Tools for Visual Studio 2017 and 2019 (see also Supported Platforms).

Intel C++ Compiler (Windows, Altix)

Qt has been tested successfully with:

  • Windows - Intel(R) C++ Compiler for 32-bit applications, Version 9.1.040.
  • Altix - Intel(R) C++ Itanium(R) Compiler for Itanium(R)-based applications Version 8.1 Build 20050406 Package ID: l_cc_pc_8.1.030

GCC (MinGW-builds)

The minimum version of MinGW-builds supported is GCC 5.1.0 (64bit, 32bit), available from its download page.

For more information about the MinGW builds, visit the Reference Configuration section of the supported platforms page.

Clang(clang-cl)

Qt has been tested successfully with Clang 3.8(llvm svn rev. 256453 and clang svn rev. 256453). Visual Studio 2015 Update 1 was used to build clang. Mkspec is using the clang-cl tool to build Qt. Clang 3.8 does not support precompiled headers.

QDoc Dependencies

QDoc uses Clang to parse C++ code. If you wish to build QDoc manually, refer to Installing Clang for QDoc for specific build requirements.

See also QDoc Dependencies.