Environment Setup & Build

Qt Upgrade Guide (macOS, Qt 5.15.16 Open Source)

Overview

This guide explains how to upgrade Qt to version 5.15.16 on macOS, supporting both Intel and Apple Silicon (arm64) environments. You can download it directly from official Qt sources or build it from source. We recommend using the official source packages for maximum compatibility.

Prerequisites

  • Administrator privileges

  • Xcode Command Line Tools installed (xcode-select --install)

  • Sufficient disk space (~15–20 GB)

  • (Optional) Homebrew installed for package management (if needed)

Removing Old Qt Installation (Optional)

For a clean upgrade:

sudo rm -rf ~/Qt

Or manually delete:

/Users/<your-username>/Qt/

Obtaining Qt 5.15.16

You have two options:

Option A – Download Prebuilt Binaries (if available)

Option B – Build from Source

If no prebuilt package is available for your platform, clone and build manually:

git clone https://code.qt.io/qt/qt5.git
cd qt5
git checkout v5.15.16
perl init-repository
./configure -prefix ~/Qt-5.15.16 -opensource -confirm-license -nomake examples -nomake tests
make -j$(sysctl -n hw.logicalcpu)
make install

Resulting install path:

/Users/<your-username>/Qt-5.15.16/

Setting Environment Variables

Add the following to your ~/.zshrc (or ~/.bash_profile):

export QTDIR=$HOME/Qt-5.15.16
export PATH=$QTDIR/bin:$PATH
export CMAKE_PREFIX_PATH=$QTDIR/lib/cmake:$CMAKE_PREFIX_PATH

Reload the profile:

source ~/.zshrc

CMake Configuration

Configure your project to use the updated Qt:

cmake .. \
  -DQt5_DIR=$QTDIR/lib/cmake/Qt5 \
  -DCMAKE_PREFIX_PATH=$QTDIR/lib/cmake

Cleaning Previous Builds

Always clean your project before rebuilding:

rm -rf build/*
mkdir build && cd build

Then re-run cmake .. and make.

Verifying Qt Installation

Check your Qt version:

qmake --version

or

qtpaths --qt-version

Confirm that you are using version 5.15.16.

Common Problems

Problem

Solution

CMake can’t find Qt5Config.cmake

Verify Qt5_DIR and CMAKE_PREFIX_PATH.

Wrong architecture (arm64 vs x86_64)

Ensure the correct Qt architecture is installed.

Qt Creator still sees an old Qt version

Update Qt paths in Qt Creator Preferences > Kits.

CMake Build

CMake Configuration

  • Windows & macOS with QtDIR environment variable set

cmake -S . -B build

  • macOS with Qt from Homebrew

cmake -S . -D USE_HOMEBREW=ON -B build

Build

cmake --build build --config Release -j 10

IDE supports

CMake supports many IDEs / Text Editors, either as a generator or fully natively. Please refer to online resources for the details. Here we provide a few pages as a starting point.