Stack Development Guide · Qt

Qt development.

Build the current stable Qt release from source with separate host and target SDKs. Version-sensitive commands on this page are rendered from a release manifest that is refreshed from Qt's official indexes and current platform documentation.

Current Qt 6.12.0 Qt Creator 20.0.2 CMake minimum 3.25 Refreshed Oct 11, 2026 10:54 UTC

Follow the current stable release, not a hard-coded guide version.

The release number, source archive name, documentation series, Qt Creator version, Android compatibility values and Emscripten target are resolved centrally. When Qt publishes a newer stable release, the guide updates its generated paths and compatibility snapshot instead of requiring every page to be edited by hand.

Use one source of truth.

If an upstream requirement changes, update the release resolver rather than copying a new version number into prose. Platform notes that cannot be safely inferred remain linked to the current official Qt platform matrix.

Separate source, build and install trees.

Do not build inside the source tree and do not mix host and target installations. A neutral host prefix works on macOS, Linux or Windows; cross-compiled targets live beside it.

LayoutCurrent release

~/Qt/
├── Src/
│   └── qt-everywhere-src-6.12.0/
├── Build/
│   └── 6.12.0/
│       ├── host/
│       ├── linux-x86_64/
│       ├── linux-arm64/
│       ├── linux-armv7/
│       ├── rpi-aarch64/
│       ├── android-arm64-v8a/
│       ├── android-armeabi-v7a/
│       ├── android-x86_64/
│       ├── android-x86/
│       ├── ios/
│       ├── ios-device/
│       ├── ios-simulator/
│       ├── wasm/
│       └── wasm-threads-simd/
├── 6.12.0/
│   ├── host/
│   ├── linux-x86_64/
│   ├── linux-arm64/
│   ├── linux-armv7/
│   ├── rpi-aarch64/
│   ├── android-arm64-v8a/
│   ├── android-armeabi-v7a/
│   ├── android-x86_64/
│   ├── android-x86/
│   ├── ios/
│   ├── ios-device/
│   ├── ios-simulator/
│   ├── wasm/
│   └── wasm-threads-simd/
└── Toolchains/
    └── emsdk/

Fetch the current stable source archive.

The archive URL below is generated from Qt's current stable release index.

ShellDownload and extract

mkdir -p "$HOME/Qt/Src"
cd "$HOME/Qt/Src"

curl -fLO "https://download.qt.io/official_releases/qt/6.12/6.12.0/single/qt-everywhere-src-6.12.0.tar.xz"
tar -xf "qt-everywhere-src-6.12.0.tar.xz"

Current target matrix.

Target	Current compatibility snapshot	Build rule
macOS	Xcode 16+	Native Apple toolchain; universal builds are optional.
Linux	Ubuntu 24.04 / Debian 11.6–12 · x86_64, arm64	Native x86_64 and arm64 are in the current supported desktop matrix; additional embedded Linux architectures require a matching toolchain and sysroot.
Embedded Linux	Raspberry Pi, Jetson, Orange Pi, BeagleBone, RISC-V boards	Use a host Qt, board-matching cross compiler, sysroot and CMake toolchain file.
Windows	MSVC 2022 · Mingw-w64 15.1	Keep MSVC and MinGW prefixes and build trees separate.
Android	Android 9–16 · API 28–36 · arm64-v8a, armeabi-v7a, x86_64, x86	Build a host Qt first, then keep each Android ABI in its own build and install tree.
iOS	Xcode 16+ · iOS 18+	Build on macOS; keep device and simulator support in the iOS target SDK.
WebAssembly	Emscripten 5.0.5	Build a matching host Qt first; keep single-threaded and threaded variants separate.

For exact architecture and distribution rows, use the current Qt supported-platforms matrix ↗. This guide intentionally avoids duplicating long-lived platform tables that upstream owns.

Desktop host

Build the host Qt first.

Android, iOS and WebAssembly source builds need host-side Qt tools from the same release. Build and verify the host SDK before any cross-compilation target.

macOS host

ShellPrepare

sudo xcode-select --switch /Applications/Xcode.app
sudo xcodebuild -license accept

brew install cmake ninja python bison flex gperf node pkg-config

cmake --version
ninja --version
xcrun clang++ --version

ShellConfigure and build host Qt

mkdir -p "$HOME/Qt/Build/6.12.0/host"
cd "$HOME/Qt/Build/6.12.0/host"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/host" \
  -release \
  -shared \
  -make examples

cmake --build . --parallel
cmake --install .

Linux host

ShellUbuntu / Debian baseline

sudo apt update
sudo apt install -y \
  build-essential \
  clang \
  cmake \
  ninja-build \
  pkg-config \
  python3 \
  bison \
  flex \
  gperf \
  nodejs

Add the X11/Wayland, OpenGL/Vulkan, multimedia, accessibility and other development packages required by the modules you intend to build. Qt's configure summary is authoritative: do not ignore a disabled feature you actually need.

Windows host

Use a Developer PowerShell for the current supported MSVC toolchain, with CMake and Ninja visible in the same environment.

PowerShellConfigure and build

mkdir C:\Qt\build\6.12.0\host
cd C:\Qt\build\6.12.0\host

C:\\Qt\\Src\\qt-everywhere-src-6.12.0\\configure.bat `
  -prefix C:\\Qt\\6.12.0\\host `
  -release `
  -shared `
  -make examples

cmake --build . --parallel
cmake --install .

Desktop · macOS

Optional universal macOS SDK.

When one Qt installation must contain both Intel and Apple Silicon slices, build a dedicated universal prefix instead of mutating the native host build.

Shellx86_64 + arm64

mkdir -p "$HOME/Qt/Build/6.12.0/macos-universal"
cd "$HOME/Qt/Build/6.12.0/macos-universal"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/macos-universal" \
  -release \
  -shared \
  -- \
  -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"

cmake --build . --parallel
cmake --install .

Desktop & Embedded · Linux

Linux architectures.

Qt's current supported desktop matrix covers x86_64 and arm64 on current Ubuntu and Debian releases. Other Linux architectures can still be built from source when you provide a matching cross compiler and sysroot, but they are not equivalent to the officially supported desktop configurations.

Architecture	Build mode	Support level
`x86_64`	Native desktop	Current supported Linux desktop architecture
`arm64 / aarch64`	Native desktop or cross-compiled	Current supported Linux desktop architecture on listed Ubuntu/Debian releases
`armv7 / armhf`	Cross-compiled embedded Linux	Requires target-specific toolchain, sysroot and device validation
`riscv64`	Cross-compiled embedded/custom Linux	Possible with a working toolchain/sysroot; not in the current mainstream desktop matrix

Native x86_64

Use this on a 64-bit Intel/AMD Linux host. Keep the install prefix architecture-specific so it never collides with ARM builds.

ShellLinux x86_64

mkdir -p "$HOME/Qt/Build/6.12.0/linux-x86_64"
cd "$HOME/Qt/Build/6.12.0/linux-x86_64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/linux-x86_64" \
  -release \
  -shared \
  -make examples

cmake --build . --parallel
cmake --install .

Native arm64 / aarch64

On an ARM64 Linux machine, build natively exactly as you would on x86_64. Qt currently lists Ubuntu 24.04 and Debian 11.6/12 ARM64 in the supported Linux matrix.

ShellLinux arm64

mkdir -p "$HOME/Qt/Build/6.12.0/linux-arm64"
cd "$HOME/Qt/Build/6.12.0/linux-arm64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/linux-arm64" \
  -release \
  -shared \
  -make examples

cmake --build . --parallel
cmake --install .

Cross-compile x86_64 host → arm64 target

Cross-compiling Qt for Linux requires a host Qt of the same release, a target sysroot and a CMake toolchain file. The example below uses the conventional aarch64-linux-gnu toolchain; replace the sysroot with the one that belongs to your actual target distribution or device.

On Ubuntu or Debian, install the matching cross compilers for the architectures you intend to build: gcc-aarch64-linux-gnu, g++-aarch64-linux-gnu, gcc-arm-linux-gnueabihf and g++-arm-linux-gnueabihf.

CMakelinux-aarch64-toolchain.cmake

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(CMAKE_SYSROOT "/opt/sysroots/aarch64-linux-gnu")
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

ShellCross-build arm64

mkdir -p "$HOME/Qt/Build/6.12.0/linux-arm64"
cd "$HOME/Qt/Build/6.12.0/linux-arm64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -release \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -extprefix "$HOME/Qt/6.12.0/linux-arm64" \
  -prefix "/usr/local/qt6" \
  -nomake tests \
  -- \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/Qt/Toolchains/linux-aarch64-toolchain.cmake"

cmake --build . --parallel
cmake --install .

Cross-compile x86_64 host → ARMv7 hard-float

ARMv7 is useful for older embedded Linux devices and 32-bit ARM boards. It is a cross-compiled embedded target, not part of the current mainstream Linux desktop support matrix. Use the sysroot and compiler that match the device image exactly.

CMakelinux-armv7-toolchain.cmake

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(CMAKE_SYSROOT "/opt/sysroots/arm-linux-gnueabihf")
set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)

set(CMAKE_C_FLAGS_INIT "-march=armv7-a -mfpu=neon -mfloat-abi=hard")
set(CMAKE_CXX_FLAGS_INIT "-march=armv7-a -mfpu=neon -mfloat-abi=hard")

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

ShellCross-build ARMv7

mkdir -p "$HOME/Qt/Build/6.12.0/linux-armv7"
cd "$HOME/Qt/Build/6.12.0/linux-armv7"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -release \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -extprefix "$HOME/Qt/6.12.0/linux-armv7" \
  -prefix "/usr/local/qt6" \
  -nomake tests \
  -- \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/Qt/Toolchains/linux-armv7-toolchain.cmake"

cmake --build . --parallel
cmake --install .

Other Linux architectures.

The same Qt 6 cross-compilation model also applies to architectures such as riscv64 when a working compiler, sysroot and graphics/input stack exist. Treat these as target-specific embedded builds unless the current Qt supported-platforms matrix explicitly lists them.

Embedded Linux · SBC

Raspberry Pi and other Linux boards.

Qt 6 uses the same cross-compilation model for Raspberry Pi and other Linux boards: a host Qt of the same release, a cross compiler, a sysroot that exactly matches the target image, and a CMake toolchain file. The old Qt 5 device-mkspec-only workflow is not sufficient for Qt 6.

Board family	Typical architecture	Notes
Raspberry Pi 5 / Raspberry Pi 4 · 64-bit OS	`aarch64 / arm64`	Recommended path for current Raspberry Pi OS and modern embedded deployments.
Raspberry Pi 4 / older Pi · 32-bit OS	`armv7 / armhf`	Use the ARMv7 hard-float toolchain and a matching 32-bit sysroot.
NVIDIA Jetson family	`aarch64`	Use the JetPack/L4T-compatible sysroot so EGL, OpenGL ES and vendor libraries match the device.
Orange Pi / Rockchip boards	`aarch64` or `armv7`	Architecture depends on the SoC and installed Linux image.
BeagleBone Black	`armv7 / armhf`	Usually cross-compiled with `arm-linux-gnueabihf`.
RISC-V development boards	`riscv64`	Requires a target-specific compiler, sysroot and graphics/input stack.

Raspberry Pi 4 / 5 · 64-bit example

Prefer an SDK or sysroot produced from the exact operating-system image running on the board. A sysroot copied from a different Raspberry Pi OS or distro revision can configure successfully and still fail later because EGL, Mesa, libc or other target libraries do not match.

ShellHost cross-compiler baseline

sudo apt update
sudo apt install -y \
  gcc-aarch64-linux-gnu \
  g++-aarch64-linux-gnu \
  cmake \
  ninja-build \
  pkg-config

export RPI_SYSROOT="$HOME/Qt/Sysroots/rpi-aarch64"
export QT_HOST="$HOME/Qt/6.12.0/host"

CMakerpi-aarch64-toolchain.cmake

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(CMAKE_SYSROOT "$ENV{RPI_SYSROOT}")

set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)

set(CMAKE_FIND_ROOT_PATH "$ENV{RPI_SYSROOT}")
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

ShellBuild Qt Base for Raspberry Pi

export RPI_SYSROOT="$HOME/Qt/Sysroots/rpi-aarch64"
export QT_HOST="$HOME/Qt/6.12.0/host"

mkdir -p "$HOME/Qt/Build/6.12.0/rpi-aarch64"
cd "$HOME/Qt/Build/6.12.0/rpi-aarch64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/qtbase/configure" \
  -release \
  -opengl es2 \
  -qt-host-path "$QT_HOST" \
  -extprefix "$HOME/Qt/6.12.0/rpi-aarch64" \
  -prefix "/usr/local/qt6" \
  -nomake examples \
  -nomake tests \
  -- \
  -DCMAKE_TOOLCHAIN_FILE="$HOME/Qt/Toolchains/rpi-aarch64-toolchain.cmake"

cmake --build . --parallel
cmake --install .

Graphics support comes from the target sysroot.

For Raspberry Pi, Jetson and similar boards, check the configure summary for the platform integration you actually need: EGLFS, Wayland, OpenGL ES or another QPA backend. A successful compiler test alone does not prove that the target graphics stack is usable.

Deploy and verify on the board

ShellExample deployment

rsync -a --delete \
  "$HOME/Qt/6.12.0/rpi-aarch64/" \
  user@raspberrypi:/usr/local/qt6/

ssh user@raspberrypi \
  '/usr/local/qt6/bin/qtpaths --qt-version'

For a 32-bit Raspberry Pi image or BeagleBone-class target, use the ARMv7 toolchain shown in the Linux architecture section and keep a separate rpi-armv7 or device-specific installation prefix.

Mobile · Android

Android.

The current manifest resolves Android 9–16, API 28–36, Build Tools 36.0.0, NDK r27c (27.2.12479018), JDK 21, Gradle 9.5.1 and AGP 9.2.1 from Qt's current documentation.

ShellInstall current Qt-compatible Android components

sdkmanager \
  "platform-tools" \
  "platforms;android-36" \
  "build-tools;36.0.0" \
  "ndk;27.2.12479018"

macOS · arm64-v8a

This is the verified source-build path on macOS when Android Studio or the Android command-line tools installed the SDK in its standard location.

ShellConfigure Qt for Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-arm64-v8a"
cd "$HOME/Qt/Build/6.12.0/android-arm64-v8a"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-arm64-v8a" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis arm64-v8a \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

ShellBuild and install

cmake --build . --parallel
cmake --install .

Supported Android ABIs

ABI	Typical use	Suggested Qt prefix
`arm64-v8a`	Primary 64-bit ARM phones and tablets	`android-arm64-v8a`
`armeabi-v7a`	Older 32-bit ARM devices	`android-armeabi-v7a`
`x86_64`	64-bit x86 Android emulators and compatible devices	`android-x86_64`
`x86`	Legacy 32-bit x86 emulator/device coverage	`android-x86`

macOS · armeabi-v7a

Shell32-bit ARM Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-armeabi-v7a"
cd "$HOME/Qt/Build/6.12.0/android-armeabi-v7a"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-armeabi-v7a" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis armeabi-v7a \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

cmake --build . --parallel
cmake --install .

macOS · x86_64

Shell64-bit x86 Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-x86_64"
cd "$HOME/Qt/Build/6.12.0/android-x86_64"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-x86_64" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis x86_64 \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

cmake --build . --parallel
cmake --install .

Optional legacy x86 build

Shell32-bit x86 Android

mkdir -p "$HOME/Qt/Build/6.12.0/android-x86"
cd "$HOME/Qt/Build/6.12.0/android-x86"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-x86" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis x86 \
  -android-sdk "$HOME/Library/Android/sdk" \
  -android-ndk "$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -release

cmake --build . --parallel
cmake --install .

First configure may spend time resolving Gradle dependencies.

Qt may download Gradle 9.5.1 and the Android Gradle Plugin 9.2.1 during dependency resolution. A Gradle BUILD SUCCESSFUL message means that dependency-resolution stage completed successfully; Qt's top-level configure must still finish without a later CMake error before the build tree is considered ready.

If Gradle times out

Populate Qt's Gradle cache explicitly, then rerun the configure command above. This keeps the actual Qt build offline with respect to Gradle dependencies.

ShellResolve Gradle dependencies once

QT_SRC="$HOME/Qt/Src/qt-everywhere-src-6.12.0"

cmake -E env \
  ANDROID_SDK_ROOT="$HOME/Library/Android/sdk" \
  cmake \
  -DACTION_RESOLVE_GRADLE=ON \
  -DQT_ROOT_DIR="$QT_SRC/qtbase" \
  -DGRADLE_PROJECT_DIR="$QT_SRC/qtbase/src/android/jar" \
  -DGRADLE_BUILD_VARIANT=Release \
  -DQT_ANDROID_SDK_BUILD_TOOLS_REVISION=36.0.0 \
  -P "$QT_SRC/qtbase/cmake/QtSetupAndroid.cmake"

Other host platforms

The configure arguments are the same; only the Android SDK path changes. Common SDK locations are ~/Android/Sdk on Linux, ~/Library/Android/sdk on macOS and C:\Users\<USER>\AppData\Local\Android\Sdk on Windows. Keep the host Qt path and Android target installation separate.

POSIX shellPortable SDK variables

export ANDROID_SDK_ROOT="/path/to/Android/Sdk"
export ANDROID_NDK_ROOT="$ANDROID_SDK_ROOT/ndk/27.2.12479018"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -prefix "$HOME/Qt/6.12.0/android-arm64-v8a" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -android-abis arm64-v8a \
  -android-sdk "$ANDROID_SDK_ROOT" \
  -android-ndk "$ANDROID_NDK_ROOT" \
  -release

Multi-ABI application packages

Build Qt once per ABI, then let the application build combine the installed Qt SDKs into a multi-ABI APK, AAB or AAR. Because these source-built prefixes use explicit names, pass their paths to CMake instead of relying on installer-directory autodetection.

Shellarm64-v8a + armeabi-v7a + x86_64

"$HOME/Qt/6.12.0/android-arm64-v8a/bin/qt-cmake" \
  -S /path/to/app \
  -B /path/to/app-build \
  -GNinja \
  -DANDROID_SDK_ROOT="$HOME/Library/Android/sdk" \
  -DANDROID_NDK_ROOT="$HOME/Library/Android/sdk/ndk/27.2.12479018" \
  -DQT_ANDROID_ABIS="arm64-v8a;armeabi-v7a;x86_64" \
  -DQT_PATH_ANDROID_ABI_arm64-v8a="$HOME/Qt/6.12.0/android-arm64-v8a" \
  -DQT_PATH_ANDROID_ABI_armeabi-v7a="$HOME/Qt/6.12.0/android-armeabi-v7a" \
  -DQT_PATH_ANDROID_ABI_x86_64="$HOME/Qt/6.12.0/android-x86_64"

cmake --build /path/to/app-build --target apk
# or:
cmake --build /path/to/app-build --target aab

Use only the ABIs your product needs. Keeping each Qt ABI in its own prefix makes upgrades, verification and multi-ABI packaging deterministic.

Mobile · iOS

iOS device and Simulator.

iOS builds run on macOS and use the Apple SDK supplied by the current Xcode toolchain. The current compatibility snapshot requires Xcode 16+ and iOS 18+. The device architecture is arm64; the simulator architecture resolved from the current Qt documentation is x86_64.

Target	SDK	Architecture	Install prefix
Device	`iphoneos`	`arm64`	`ios-device`
Simulator	`iphonesimulator`	`x86_64`	`ios-simulator`
Combined Qt SDK	Device + Simulator	Qt-managed	`ios`

Default: build one Qt for iOS SDK containing device and Simulator libraries

Qt's default iOS source build includes both device and Simulator libraries. Use this when a single Qt installation should drive both Xcode run destinations.

ShellCombined iOS SDK

mkdir -p "$HOME/Qt/Build/6.12.0/ios"
cd "$HOME/Qt/Build/6.12.0/ios"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -platform macx-ios-clang \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -prefix "$HOME/Qt/6.12.0/ios" \
  -release

cmake --build . --parallel
cmake --install .

Device-only SDK

Use -sdk iphoneos when you want a dedicated physical-device Qt installation.

Shelliphoneos · arm64

mkdir -p "$HOME/Qt/Build/6.12.0/ios-device"
cd "$HOME/Qt/Build/6.12.0/ios-device"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -platform macx-ios-clang \
  -sdk iphoneos \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -prefix "$HOME/Qt/6.12.0/ios-device" \
  -release

cmake --build . --parallel
cmake --install .

Simulator-only SDK

Use -sdk iphonesimulator for a dedicated Simulator Qt installation.

Shelliphonesimulator · x86_64

mkdir -p "$HOME/Qt/Build/6.12.0/ios-simulator"
cd "$HOME/Qt/Build/6.12.0/ios-simulator"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -platform macx-ios-clang \
  -sdk iphonesimulator \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -prefix "$HOME/Qt/6.12.0/ios-simulator" \
  -release

cmake --build . --parallel
cmake --install .

Apple Silicon: the current Qt iOS Simulator libraries are x86_64.

The Simulator run destination therefore uses Rosetta on Apple Silicon Macs. With Xcode 26 or newer, install the universal iOS platform component if the Rosetta-based Simulator destination is missing:

ShellXcode 26+

xcodebuild -downloadPlatform iOS -architectureVariant universal

Build an application

Use the qt-cmake from the selected iOS Qt prefix. The generated Xcode project can then run on the physical device or Simulator destination represented by that SDK.

ShellSimulator application

"$HOME/Qt/6.12.0/ios-simulator/bin/qt-cmake" \
  -S /path/to/app \
  -B /path/to/app-build-ios-simulator \
  -G Xcode

cmake --build /path/to/app-build-ios-simulator \
  --config Release

Do not manually force a different Simulator architecture unless the current Qt iOS documentation explicitly supports it. The release manifest tracks the Simulator architecture from Qt's current upstream documentation.

Web · WebAssembly

WebAssembly.

Each Qt minor release targets a specific Emscripten version. The current resolver pins 5.0.5. Use that exact version for the baseline build and keep the emsdk installation isolated from unrelated Emscripten projects.

macOS / Linux: install and activate the matching Emscripten SDK

POSIX shellInstall · activate · verify

export EMSCRIPTEN_VERSION="5.0.5"
export EMSDK_ROOT="$HOME/Qt/Toolchains/emsdk"

mkdir -p "$HOME/Qt/Toolchains"

if [ ! -d "$EMSDK_ROOT/.git" ]; then
  git clone https://github.com/emscripten-core/emsdk.git "$EMSDK_ROOT"
fi

cd "$EMSDK_ROOT"

./emsdk install "$EMSCRIPTEN_VERSION"
./emsdk activate "$EMSCRIPTEN_VERSION"

test -f "$EMSDK_ROOT/.emscripten" || {
  echo "Emscripten activation failed: $EMSDK_ROOT/.emscripten is missing" >&2
  exit 1
}

source "$EMSDK_ROOT/emsdk_env.sh"

command -v em++
em++ --version
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

install and activate are two separate commands.

If they are accidentally pasted together, the SDK is not activated and .emscripten is not created. Sourcing emsdk_env.sh alone is not enough. Qt reads $EMSDK/.emscripten during WebAssembly auto-detection.

Repair an emsdk checkout that shows `.emscripten: No such file or directory`

POSIX shellRepair the active SDK

export EMSCRIPTEN_VERSION="5.0.5"
cd "$HOME/Qt/Toolchains/emsdk"

./emsdk install "$EMSCRIPTEN_VERSION"
./emsdk activate "$EMSCRIPTEN_VERSION"
source ./emsdk_env.sh

test -f "$EMSDK/.emscripten"
em++ --version
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

If em++ --version still reports a different development version such as *-git, do not continue with the baseline Qt build. Re-run activate, source the environment again, and verify the version before configuring Qt.

Windows PowerShell installation

Run this block only in PowerShell on Windows. Do not paste Set-Location, .bat or .ps1 commands into zsh/bash on macOS or Linux.

PowerShellWindows · install · activate · verify

$env:EMSCRIPTEN_VERSION = "5.0.5"
$emsdkRoot = "$HOME\Qt\Toolchains\emsdk"

if (-not (Test-Path "$emsdkRoot\.git")) {
    git clone https://github.com/emscripten-core/emsdk.git $emsdkRoot
}

Set-Location $emsdkRoot

.\emsdk.bat install $env:EMSCRIPTEN_VERSION
.\emsdk.bat activate $env:EMSCRIPTEN_VERSION
.\emsdk_env.ps1

em++ --version

Baseline single-threaded SDK

After a failed configure, remove the incomplete build tree before trying again. A failed configure does not create a usable build.ninja or cmake_install.cmake.

ShellConfigure and build

export EMSCRIPTEN_VERSION="5.0.5"
export EMSDK_ROOT="$HOME/Qt/Toolchains/emsdk"

cd "$EMSDK_ROOT"
./emsdk activate "$EMSCRIPTEN_VERSION"
source "$EMSDK_ROOT/emsdk_env.sh"

test -f "$EMSDK_ROOT/.emscripten"
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

rm -rf "$HOME/Qt/Build/6.12.0/wasm"
mkdir -p "$HOME/Qt/Build/6.12.0/wasm"
cd "$HOME/Qt/Build/6.12.0/wasm"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -platform wasm-emscripten \
  -prefix "$HOME/Qt/6.12.0/wasm" \
  -release

cmake --build . --parallel
cmake --install .

Threads + SIMD build

ShellPerformance-oriented variant

export EMSCRIPTEN_VERSION="5.0.5"
export EMSDK_ROOT="$HOME/Qt/Toolchains/emsdk"

cd "$EMSDK_ROOT"
./emsdk activate "$EMSCRIPTEN_VERSION"
source "$EMSDK_ROOT/emsdk_env.sh"

test -f "$EMSDK_ROOT/.emscripten"
em++ --version | grep -F "$EMSCRIPTEN_VERSION"

rm -rf "$HOME/Qt/Build/6.12.0/wasm-threads-simd"
mkdir -p "$HOME/Qt/Build/6.12.0/wasm-threads-simd"
cd "$HOME/Qt/Build/6.12.0/wasm-threads-simd"

"$HOME/Qt/Src/qt-everywhere-src-6.12.0/configure" \
  -qt-host-path "$HOME/Qt/6.12.0/host" \
  -platform wasm-emscripten \
  -prefix "$HOME/Qt/6.12.0/wasm-threads-simd" \
  -release \
  -feature-thread \
  -feature-wasm-simd128

cmake --build . --parallel
cmake --install .

Browser capabilities are part of the toolchain.

Threaded WebAssembly requires cross-origin isolation and a secure context. Features such as SIMD, exceptions, dynamic linking and Asyncify must be verified against the current Qt WebAssembly documentation and the browsers you actually ship to.

What “full Qt” means.

Use the complete Qt source package and avoid -skip unless a module is intentionally excluded. Qt still builds only modules supported by the current target and whose external dependencies are satisfied. A desktop host, Android, iOS and WebAssembly are separate SDKs and do not expose identical module sets.

Read the configure summary.

A successful command is not enough if a required feature was silently disabled because a system dependency was missing. Treat every unexpectedly disabled feature as a configuration failure.

Modern Qt projects stay modern C++ projects.

Qt does not justify returning to header-first architecture or old console idioms. Keep domain/application code in project modules, use Qt Quick/QML as the presentation adapter for new graphical applications, and keep the C++/QML boundary explicit.

CMakeModule-based Qt Quick baseline

cmake_minimum_required(VERSION 3.30)

project(GenyleapSample
    VERSION 0.1.0
    LANGUAGES CXX
)

add_library(genyleap_sample_core)

target_compile_features(genyleap_sample_core
    PUBLIC
        cxx_std_26
)

target_sources(genyleap_sample_core
    PUBLIC
        FILE_SET CXX_MODULES
        FILES
            src/domain/app_domain.cppm
    PRIVATE
        src/domain/app_domain.cpp
)

set_property(
    TARGET genyleap_sample_core
    PROPERTY CXX_SCAN_FOR_MODULES ON
)

find_package(Qt6 6.12 REQUIRED COMPONENTS
    Quick
    Qml
    QuickControls2
)

if(QT_KNOWN_POLICY_QTP0004)
    qt_policy(SET QTP0004 NEW)
endif()

qt_standard_project_setup(REQUIRES 6.12)

qt_add_executable(GenyleapSample
    src/bootstrap/main.cpp
)

qt_add_qml_module(GenyleapSample
    URI Genyleap.Sample
    VERSION 1.0
    QML_FILES
        ui/Main.qml
)

target_link_libraries(GenyleapSample
    PRIVATE
        genyleap_sample_core
        Qt6::Quick
        Qt6::Qml
        Qt6::QuickControls2
)

target_compile_features(GenyleapSample
    PRIVATE
        cxx_std_26
)

C++src/bootstrap/main.cpp

#include <cstdlib>

#include <QCoreApplication>
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QObject>
#include <QQuickStyle>
#include <QString>

int main(int argc, char* argv[])
{
    QGuiApplication application {argc, argv};

    QQuickStyle::setStyle(QStringLiteral("Basic"));

    QQmlApplicationEngine engine;

    QObject::connect(
        &engine,
        &QQmlApplicationEngine::objectCreationFailed,
        &application,
        [] {
            QCoreApplication::exit(EXIT_FAILURE);
        },
        Qt::QueuedConnection
    );

    engine.loadFromModule("Genyleap.Sample", "Main");

    return application.exec();
}

Do not use experimental import std; as a reason to abandon modules.

Project-owned C++ modules remain the architecture. Standard-library headers can stay textual in the global module fragment until the standard-module path is a deliberate, verified project choice.

IDE

Install and configure Qt Creator.

The current stable Qt Creator release resolved from Qt's official latest index is 20.0.2. The official standalone package installs the IDE only; your self-built Qt SDKs stay where they are and are registered afterward as Qt versions and kits.

macOS · official universal package

ShellQt Creator 20.0.2

cd "$HOME/Downloads"
curl -fLO "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-mac-universal-20.0.2_installer.dmg"
open "qt-creator-opensource-mac-universal-20.0.2_installer.dmg"

As a convenient package-manager alternative, brew install --cask qt-creator is available, but Qt does not officially support package-manager builds of Qt Creator.

Linux · official standalone installer

x86_64

ShellLinux x86_64

cd "$HOME/Downloads"
curl -fLO "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-linux-x86_64-20.0.2.run"
chmod +x "qt-creator-opensource-linux-x86_64-20.0.2.run"
./"qt-creator-opensource-linux-x86_64-20.0.2.run"

arm64

ShellLinux arm64

cd "$HOME/Downloads"
curl -fLO "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-linux-arm64-20.0.2.run"
chmod +x "qt-creator-opensource-linux-arm64-20.0.2.run"
./"qt-creator-opensource-linux-arm64-20.0.2.run"

Distribution packages can lag behind the current Qt Creator release, so use the official installer when the development stack is expected to track the current release.

Windows · official standalone installer

x86_64

PowerShellWindows x86_64

Set-Location "$HOME\Downloads"
Invoke-WebRequest -Uri "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-windows-x86_64-20.0.2.exe" -OutFile "qt-creator-opensource-windows-x86_64-20.0.2.exe"

Start-Process -Wait ".\qt-creator-opensource-windows-x86_64-20.0.2.exe"

ARM64

PowerShellWindows ARM64

Set-Location "$HOME\Downloads"
Invoke-WebRequest -Uri "https://download.qt.io/official_releases/qtcreator/latest/qt-creator-opensource-windows-arm64-20.0.2.exe" -OutFile "qt-creator-opensource-windows-arm64-20.0.2.exe"

Start-Process -Wait ".\qt-creator-opensource-windows-arm64-20.0.2.exe"

choco install qtcreator is also available as a package-manager alternative on Windows, with the same caveat that package-manager distributions are not the officially supported delivery path.

Register the self-built Qt SDKs

Prove the CLI build first

Compiler, CMake, Ninja and the target's qt-cmake must work outside the IDE.

Add the Qt version

Open Preferences → Kits → Qt Versions → Add and select that Qt installation's bin/qtpaths or bin/qmake. For the desktop host, use $HOME/Qt/6.12.0/host/bin/qtpaths.

Create one kit per target

Keep Desktop, Android, iOS, iOS Simulator, WebAssembly and Remote Linux/embedded-device settings in separate kits.

Bind the toolchain

For each kit, select the matching compiler, CMake executable, Ninja generator, debugger, Qt version and run device. Do not let a host compiler leak into a cross-compiled target kit.

ShellVerify the host Qt before registering it

"$HOME/Qt/6.12.0/host/bin/qtpaths" --qt-version
"$HOME/Qt/6.12.0/host/bin/qtpaths" --install-prefix
"$HOME/Qt/6.12.0/host/bin/qt-cmake" --version

Raspberry Pi and other boards belong in a Remote Linux kit.

Add the board under Preferences → Devices, then create a kit that uses the matching cross compiler, self-built embedded Qt prefix and remote run device. Qt Creator can deploy and run the application over the configured device connection.

Qt WebEngine and Qt PDF are independently version-sensitive.

Do not derive the WebEngine/PDF version mechanically from the base Qt version. Their release cadence can differ from the main Qt package. Treat them as separately resolved dependencies and verify the current release notes before adding them to a source-build baseline.

Verify every target before calling it ready.

ShellHost SDK

"$HOME/Qt/6.12.0/host/bin/qtpaths" --qt-version
"$HOME/Qt/6.12.0/host/bin/qtpaths" --install-prefix
"$HOME/Qt/6.12.0/host/bin/qt-cmake" --version

Then configure and build a real application with the target's own qt-cmake. For graphical applications, a core-library build is not sufficient evidence: generated MOC, QML type registration, resources, QML lint and a deterministic runtime smoke path all belong to final verification.

Current upstream references.

Supported platformsCurrent desktop, mobile and WebAssembly compatibility matrix ↗ Build Qt for macOSCurrent Apple host and universal-build requirements ↗ Build Qt for LinuxCurrent x86_64 and arm64 desktop source-build guidance ↗ Cross-compile Qt for Linux devicesToolchain-file and sysroot model for ARM and other embedded targets ↗ Build Qt for AndroidCurrent host Qt, SDK, NDK and ABI guidance ↗ Android multi-ABI applicationsPackage multiple Qt ABI builds into APKs, AABs and AARs ↗ Build Qt for iOSCurrent device and simulator source-build guidance ↗ Qt for WebAssemblyCurrent Emscripten target and browser constraints ↗ Qt Creator latestCurrent stable Qt Creator download index ↗ Install Qt CreatorOfficial installation methods for macOS, Linux and Windows ↗ Register self-built Qt versionsAdd qmake or qtpaths and create matching kits ↗ Remote Linux devicesConfigure, deploy and run on Raspberry Pi and other Linux boards ↗ AI for Modern C++Modern module, CMake, Qt Quick and verification contract used by these examples ↗

Qt development.

Follow the current stable release, not a hard-coded guide version.

Separate source, build and install trees.

Fetch the current stable source archive.

Current target matrix.

Build the host Qt first.

macOS host

Linux host

Windows host

Optional universal macOS SDK.

Linux architectures.

Native x86_64

Native arm64 / aarch64

Cross-compile x86_64 host → arm64 target

Cross-compile x86_64 host → ARMv7 hard-float

Raspberry Pi and other Linux boards.

Raspberry Pi 4 / 5 · 64-bit example

Deploy and verify on the board

Android.

macOS · arm64-v8a

Supported Android ABIs

macOS · armeabi-v7a

macOS · x86_64

If Gradle times out

Other host platforms

Multi-ABI application packages

iOS device and Simulator.

Default: build one Qt for iOS SDK containing device and Simulator libraries

Device-only SDK

Simulator-only SDK

Build an application

WebAssembly.

macOS / Linux: install and activate the matching Emscripten SDK

Repair an emsdk checkout that shows .emscripten: No such file or directory

Baseline single-threaded SDK

Threads + SIMD build

What “full Qt” means.

Modern Qt projects stay modern C++ projects.

Install and configure Qt Creator.

macOS · official universal package

Linux · official standalone installer

x86_64

arm64

Windows · official standalone installer

x86_64

ARM64

Register the self-built Qt SDKs

Prove the CLI build first

Add the Qt version

Create one kit per target

Bind the toolchain

Qt WebEngine and Qt PDF are independently version-sensitive.

Verify every target before calling it ready.

Current upstream references.

Repair an emsdk checkout that shows `.emscripten: No such file or directory`