Qt Reference Documentation

Platform Notes - Mac OS X

This page contains information about the Mac OS X versions Qt is currently known to run on, with links to platform-specific notes. More information about the combinations of platforms and compilers supported by Qt can be found on the Supported Platforms page.

General Information

Qt 4.6 applications can only be deployed on Mac OS X 10.4 (Tiger) and higher.

Qt 4.4 and Qt 4.5 development is only supported on Mac OS X 10.4 and up. Applications built against these version of Qt can be deployed on Mac OS X 10.3, but cannot be developed on that version of the operating system due to compiler issues.

Qt 4.3 has been tested to run on Mac OS X 10.3.9 and up. See notes on the binary package for more information.

Qt 4.1 has been tested to run on Mac OS X 10.2.8 and up. Qt 4.1.4 is the last release to work with Mac OS X 10.2.

Required GCC version

Apple's gcc 4 that is shipped with the Xcode Tools for both Mac OS X 10.4 and 10.5 will compile Qt. There is preliminary support for gcc 4.2 which is included with Xcode Tools 3.1+ (configurable with -platform macx-g++42).

Binary Package

The binary package requires that you have your .qt-license file in your home directory. Installer.app cannot complete without a valid .qt-license file. Evaluation users of Qt will have information about how to create this file in the email they receive.

The binary package was built on Mac OS X 10.4 with Xcode Tools 2.1 (gcc 4.0.0) for Qt 4.1.0, Xcode Tools 2.2 (gcc 4.0.1) for Qt 4.1.1-4.1.4 and Xcode Tools 2.3 for 4.2.0. It will only link executables built against 10.4 (or a 10.4 SDK). You should be able to run applications linked against these frameworks on Mac OS X 10.3.9 and Mac OS X 10.4+. If you require a different configuration, you will have to use the source package and build with GCC 3.3.

Mac OS X on Intel hardware

Qt 4 fully supports both the Intel and PowerPC architectures on the Mac. As of Qt 4.1 it is possible to support the Intel architecture by creating Universal Binaries with qmake. As of Qt 4.1 it is possible to build Qt as a set of universal binaries and frameworks from configure by adding these extra flags:

 -universal -sdk /Developer/SDKs/MacOSX10.4u.sdk

If you are building on Intel hardware you can omit the sdk parameter, but PowerPC hardware requires it.

You can also generate universal binaries using qmake. Simply add these lines to your .pro file:

 CONFIG+=x86 ppc

Build Issues

If Qt does not build upon executing make, and fails with an error message such as

 /usr/bin/ld: /System/Library/Frameworks/Carbon.framework/Carbon
 load command 20 unknown cmd field
 /usr/bin/ld: /usr/lib/libSystem.dylib
 load command 6 unknown cmd field

this could be an indication you have upgraded your version of Mac OS X (e.g. 10.3 to 10.4), without upgrading your Developer Tools (Xcode Tools). These must match in order to successfully compile files.

Please be sure to upgrade both simultaneously. If problems still occur, contact support.


If you have installed the Qt for X11 package from Fink, it will set the QMAKESPEC environment variable to darwin-g++. This will cause problems when you build the Qt for Mac OS X package. To fix this, simply unset your QMAKESPEC or set it to macx-g++ before you run configure. You need to have a fresh Qt distribution (make confclean).

MySQL and Mac OS X

There seems to be a issue when both -prebind and -multi_module are defined when linking static C libraries into dynamic library. If you get the following error message when linking Qt:

 ld: common symbols not allowed with MH_DYLIB output format with the -multi_module option
 /usr/local/mysql/lib/libmysqlclient.a(my_error.o) definition of common _errbuff (size 512)
 /usr/bin/libtool: internal link edit command failed

re-link Qt using -single_module. This is only a problem when building the MySQL driver into Qt. It does not affect plugins or static builds.

Qt and Precompiled Headers (PCH)

Starting with Qt 3.3.0 it is possible to use precompiled headers. They are not enabled by default as it appears that some versions of Apple's GCC and make have problems with this feature. If you want to use precompiled headers when building the Qt source package, specify the -pch option to configure. If, while using precompiled headers, you encounter an internal compile error, try removing the -include header statement from the compile line and trying again. If this solves the problem, it probably is a good idea to turn off precompiled headers. Also, consider filing a bug report with Apple so that they can improve support for this feature.


Thank you for giving your feedback.

Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.

[0]; s.parentNode.insertBefore(ga, s); })();