Build Qt5 on iOS

Introduction

We will build Qt5.15.19 for iOS. Unlike the Linux and Windows builds, this build does not include Qt WebEngine.

This is not a choice, it is an Apple restriction. Apple does not allow Qt WebEngine, or any other third-party rendering engine, on iOS. Every app that displays web content must use WebKit (WKWebView). So on iOS, garlic-player has to rely on WebKit instead of QWebEngine, and Qt WebEngine is skipped from the build entirely.

This has a welcome side effect: because QWebEngine is skipped entirely, the build also works with the current Xcode 26.6 (2026), even though Qt5.15 predates it by several years. QWebEngine is the component that usually breaks first with newer Xcode and SDK versions, so leaving it out removes the main source of incompatibility.

Using a recent Xcode matters beyond just compiling. Apple requires apps to be built and submitted with a current Xcode and SDK version to be accepted into the App Store. Sticking to an old Xcode just to keep Qt5.15 compiling would eventually block App Store submissions altogether.

Requirements

• A Mac with Xcode installed. This guide was tested with Xcode 26.6 (2026). I used macOS 26 (Tahoe)
• Qt5.15.19 source code from the Qt Archive, Qt version 5.15.8 or newer is supported.
• iOS builds can only be produced on macOS, since Xcode and the iOS SDK are required. Cross-compiling from Linux or Windows is not supported by Qt for this target.
• At least 15 GB of free disk space. 16 GB of RAM is recommended for a smooth multi-core build. 8 GB can work, but you will likely need to lower the number of parallel jobs to avoid running out of memory.

Build Steps for Qt on iOS

The build is driven by a small shell script that sets a few variables (Qt version, base path, number of parallel jobs, and which Xcode to use) and then runs the actual build steps below. We will go through those steps directly.

Enter the Shadow Build Directory

mkdir -p build-5.15.19
cd build-5.15.19

As with the other platforms, a shadow build directory keeps build artifacts separate from the Qt source tree, which makes cleanup and parallel configurations much easier.

Configure Qt for iOS

$QT_SRC/configure -xplatform macx-ios-clang \
    -release -optimize-size \
	-opensource -confirm-license -nomake tests -nomake examples \
    -no-openssl -securetransport \
    -no-pch \
    -prefix /path/to/Ot/install-dir \
    -skip qttranslations \
    -skip qtserialport \
    -skip qtwayland \
    -skip qtwebengine \
    -skip qtscript \
    -skip qt3d \
    -skip qtlocation \
    -skip qtdoc \
    -skip qtpurchasing \
    -skip qtvirtualkeyboard \
    -skip qtspeech

Configure Explanations

• -xplatform macx-ios-clang: Selects the iOS platform spec. This is what makes configure build for iOS devices and the simulator instead of macOS.
• -release -optimize-size: Builds a release configuration and optimizes the resulting binaries for size rather than speed, which matters for app bundle size on iOS.
• -opensource -confirm-license: Accepts the open source license non-interactively, required for automated builds.
• -nomake tests -nomake examples: Skips building the Qt test suite and example programs, saving build time.
• -no-openssl -securetransport: Disables OpenSSL and uses Apple’s Secure Transport framework for TLS instead. This is the standard choice on iOS, since bundling OpenSSL is generally avoided in App Store builds.
• -no-pch: Disables precompiled headers. Precompiled headers can cause issues with certain Xcode and SDK combinations on iOS, so this build avoids them.
• -prefix $QT_INSTALL_DIR: Defines where make install will place the resulting Qt binaries.
• -skip …: ActiveQt, SerialPort, Qt3D, Wayland, and the other listed modules are not needed for garlic-player on iOS. qtwebengine is skipped here as well, and as explained above, it is not built separately afterward since Apple does not permit it on iOS at all.

If something is missing or fails, configure will print a more or less detailed notice. If everything completes fine, continue to the next step.

Build

make -j12

The -j value sets the number of parallel compile jobs. Lower it if you run out of memory. On a modern Mac with 16 GB of RAM, this step typically takes 30 to 60 minutes, considerably faster than a desktop build with QWebEngine since that component is skipped entirely.

Install

make install

This installs the compiled Qt libraries into the prefix directory, ready to be used as an iOS Qt kit in Qt Creator or referenced directly from Xcode project settings.

Verify the installation

path/to/qt/5.15.19/ios/bin/qmake -v

This should print the Qt version along with the iOS platform spec used to build it.

Troubleshooting

• configure fails looking for Xcode: Confirm your Xcode developer directory is set correctly and that xcode-select -p reports the expected path.
• configure or make fails after an Xcode update: Re-run sudo xcodebuild -license accept and make sure command line tools are installed with xcode-select --install.
• make fails with “out of memory” or the process gets killed: Lower the number of parallel jobs and try again.
• App Store submission rejected for SDK version: Make sure the app is built and archived with the same recent Xcode used for this Qt build, not an older one kept around for compatibility.

Share Your Thoughts

If you have any ideas, suggestions for improvement, or run into issues with a specific Xcode version, feel free to reach out. You can share your feedback by email or by giving my project a star on GitHub.