aqtinstall: Command-Line Qt Installation Across Platforms

Why aqtinstall Exists for Qt Provisioning

aqtinstall addresses a practical gap in Qt distribution: the official graphical installer is not suitable for CI jobs or other environments without an interactive user interface. The project describes itself as an unofficial alternative and provides an `aqt` command that can download prebuilt Qt binaries, documentation, and source packages from Qt distribution sites and their mirrors. The intended users are developers and automation systems that need a specific Qt SDK assembled as part of a build or deployment process.

The CLI makes the target explicit. A request identifies the host, target platform, Qt version, and architecture, with optional modules. That specificity matters in CI because a generic installer interaction is difficult to reproduce. It also lets a build declare which Qt artifacts it needs instead of accepting everything that happens to be available in an interactive session. The README gives Windows desktop, MinGW, Android, desktop toolsets, and iOS examples, so the documented scope extends beyond one operating system.

This is an installer utility, not a complete Qt development environment manager. It downloads packages, extracts them, and updates selected package configuration files. It does not install every compiler, system library, or environment variable that a Qt application may require. The distinction matters for adoption. A CI image that needs Qt through `PATH`, `QT_PLUGIN_PATH`, `QML_IMPORT_PATH`, or `QML2_IMPORT_PATH` still needs configuration outside aqtinstall.

How aqtinstall Selects and Installs Qt Artifacts

The documented workflow is query first, install second. The `list-qt` subcommand queries available architectures or modules for a particular host and Qt version. Once the required target is identified, `install-qt` downloads the corresponding prebuilt packages. For example, the README separates architecture discovery from module discovery, then uses the selected architecture in the install command.

During installation, aqtinstall updates package configuration such as `bin/qt.conf` and `bin/qconfig.pri`. Those changes make the downloaded package work with its installed directory. The package metadata and distribution files are defined in `pyproject.toml`, where the project declares the `aqt` console script as `aqt = "aqt.__main__:main"`. Dependencies include `requests`, `py7zr`, `patch-ng`, `semantic-version`, `texttable`, `bs4`, and `defusedxml`, which correspond to network retrieval, archive extraction, patching, metadata handling, and parsing needs.

The architecture is a client-side package selection layer over Qt distribution files. aqtinstall does not compile Qt from source. It selects prebuilt artifacts that are already published for the requested combination. This makes the process suitable for provisioning a known toolchain, but it also means availability is constrained by what Qt mirror sites currently publish. The README warns that The Qt Company may remove versions that have reached end of support. A build pinned to an older release can therefore become dependent on mirror availability outside aqtinstall's control.

Installing the CLI and Running a First Qt Query

The package requires Python 3.10 or later. The README recommends updating `pip` before installation because aqtinstall depends on packages that may be delivered as precompiled wheels on several platforms. On Windows, the project also offers `aqt.exe`, a standalone executable containing Python and its dependencies, when setting up the required Python environment is inconvenient.

Install the command from PyPI:

pip install -U pip
pip install aqtinstall

The first useful step is to query the available Windows desktop architectures for Qt 6.2.0:

aqt list-qt windows desktop --arch 6.2.0

The README shows possible results such as `win64_mingw81`, `win64_msvc2019_64`, and `win64_msvc2019_arm64`. The exact list depends on the Qt distribution data available at the time of the query. This command does not install Qt. It gives the caller the target names needed for the next operation.

For a Python-based installation, the `aqt` command is registered through the package's console script. On MSYS2 or MinGW64 environments, the README instructs users to set `SETUPTOOLS_USE_DISTUTILS=stdlib` because setuptools can otherwise raise a `VC6.0 is not supported` error in that environment. That setting addresses a packaging environment issue, not a Qt installation option.

Installing Windows Qt with MinGW Modules

After selecting an architecture, the README uses `win64_mingw81` as the target for a Qt 6.2.0 installation. The `-m all` option requests every module available for that release and architecture:

aqt install-qt windows desktop 6.2.0 win64_mingw81 -m all

The optional module argument can be omitted when a minimal SDK is sufficient. If only selected modules are needed, their names can be passed after `-m`. The README specifies lowercase names for the example:

aqt install-qt windows desktop 6.2.0 win64_mingw81 -m qtcharts qtnetworking

This selection is useful in CI because the command records the intended Qt release and modules in the build definition. It also avoids installing every optional module when a project only needs `qtcharts` and `qtnetworking`. The command does not, however, install the MinGW compiler itself. The README lists MinGW as a target or architecture concept, while the environment requirements for compiling or running Qt applications remain separate responsibilities.

After extraction, aqtinstall updates `bin/qt.conf` and `bin/qconfig.pri`. The README explicitly says that setting `PATH`, `QT_PLUGIN_PATH`, `QML_IMPORT_PATH`, and `QML2_IMPORT_PATH` is left to the user. That restraint avoids modifying global or shared environment state, which matters when a machine or CI workspace contains several Qt versions. The result is more deliberate integration work, but it also reduces the chance that one installation silently changes another.

Android, iOS, and Platform Boundaries

aqtinstall supports target combinations beyond desktop Windows. The README gives an Android example that requests desktop toolsets along with an Android architecture:

aqt install-qt linux android 5.13.2 android_armv7 --autodesktop

The `--autodesktop` option is the documented mechanism for including the required desktop toolsets in that command. It is specific to the installation scenario and should not be generalized to every aqtinstall target.

iOS has a narrower compatibility boundary. The README warns about compatibility problems between Xcode 13 and later and Qt versions older than 6.2.4. It says aqtinstall is tested for iOS on macOS 12 with Qt 6.2.4 and greater, while earlier Qt versions are expected not to function with the most recent macOS versions. This is a platform and host-toolchain constraint, not merely an aqtinstall installation error. A team choosing an older Qt version for an iOS build must account for the current Xcode and macOS combination separately.

The project lists Linux, macOS, and MS Windows as supported operating systems. That host support does not guarantee that every Qt target is available for every host. The distribution mirror is the deciding layer, and the requested version or architecture may no longer be present. For reproducible builds, the availability of a particular Qt release should be checked before a pipeline depends on it.

Maintenance, Packaging, and Licensing Boundaries

The repository is not archived, and its last push was on 2026-09-11. The project has also published releases, including v3.3.0 on 2025-06-02, v3.2.1 on 2025-03-16, and v3.2.0 on 2025-01-28. That is evidence of recent project activity, but it does not remove the operational dependency on external Qt distribution infrastructure. Maintenance of aqtinstall and availability of the Qt artifacts it selects are separate concerns.

The package metadata identifies the project as `aqtinstall` and provides the `aqt` command through the Python entry point. Python 3.10 is the minimum supported version. For users who cannot assemble Python and all dependencies on Windows, the repository documents `aqt.exe` in the release assets and a persistent continuous-build link. The continuous build is not the same as a versioned release, so production pipelines that require repeatable software selection should distinguish the two sources.

aqtinstall itself is distributed under the MIT license. The README separately states that the Qt SDK and related files use their own licenses, and that using aqtinstall means agreeing to the Qt licenses. It describes the installed Qt SDK as being under a `(L)GPL Free Software` designation in the context of that utility. Anyone using commercial Qt components must review the applicable Qt licensing terms rather than treating the MIT license of aqtinstall as covering the downloaded SDK.

Headless Qt Installers and Other Provisioning Approaches

The closest alternative named by the README is the official graphical Qt installer. Its main difference is the interaction model. The graphical installer is designed for a user operating an installer interface, while aqtinstall exposes target selection through commands suitable for scripts and CI. The trade-off is explicit control versus an interactive workflow. aqtinstall does not remove all setup work because it deliberately leaves environment variables and unrelated toolchains to the caller.

Another approach is to package a Qt SDK into a prebuilt container image or CI image. That moves installation and configuration work outside the build job and can make startup predictable, but it also requires maintaining the image and its contents. aqtinstall instead resolves and downloads packages during the installation step, which is useful when a pipeline needs to select a Qt version as part of its declared setup. The README points to GitHub Actions, Azure Pipelines, and Docker examples as uses by other projects, but those references are examples rather than proof that a particular integration is maintained by aqtinstall.

For a team that wants direct download control, aqtinstall offers a narrower and scriptable path than a graphical installer. For a team that wants a fully prepared runtime with compiler, libraries, and environment variables already configured, a maintained image may be the better fit. aqtinstall is the better fit when the pipeline needs to choose individual Qt modules and versions without depending on a prebuilt environment snapshot.

Editorial conclusion

Adopt aqtinstall when a build environment needs reproducible, command-driven Qt package selection and can work with the available Qt mirrors. Do not choose it when an interactive installer or automatic environment setup is required. Verify Python 3.10 or later, the selected Qt version and architecture, required modules, Qt licensing, and whether your CI platform needs `aqt.exe` or the package installed through `pip` first.

Frequently asked questions

Official sources

1. License: MIT
2. miurahr/aqtinstall on GitHub
3. Project website
4. README
5. Releases