install-qt-action turns Qt setup in GitHub Actions into two YAML lines

The whole point is the two lines you stop writing

The argument for this action is made in the first line of its documentation, which states that installing Qt on GitHub Actions workflows manually is the worst. What follows is the entire replacement:

    - name: Install Qt
      uses: jurplel/install-qt-action@v4

Two lines, and the toolchain is in place. That framing is worth taking seriously because Qt in CI is a genuinely large install, and the fiddly part is not the download but the matrix of decisions about which package to fetch.

The action is written in TypeScript, lives under an action directory with an action.yml at the top of the repository, and ships a tests directory. It is MIT licensed. The maintenance record is strong: v4.4.1 on 2026-09-20, v4.4.0 on 2026-09-14, v4.3.1 on 2026-04-08, and the last push was on 2026-10-20.

The repository also has a contributing guide and a separate upgrade guide, README_upgrade_guide.md, which exists because each new major version of the action can break workflows written against an older one. That is a warning worth reading before you bump the major version, since a Qt install failing is a confusing way to discover a breaking change.

Version defaults to a tested Qt 6 LTS build

The version option takes the Qt version you want, and it is more flexible than a single number. You can pass SimpleSpec version ranges or wildcards, with the documentation giving 6.2.* and >=6.2.0,<6.5.0 as the examples.

There is a warning attached to the wildcard behaviour that will bite someone. Beta releases are not excluded if the version range is too large, so a range such as >=6.*.* will pull in prereleases, and you need to set ranges and wildcard patterns accordingly to avoid that.

The default is 6.8.3, described as a tested Qt 6 LTS version for open-source licensed users. So the action is opinionated about where it starts you: a long term support release that has been checked against the open source licensing terms, rather than the newest thing available.

There is one platform constraint attached to the version option rather than the platform options, and it is easy to skim past. For Linux builds, Qt 6 and later require Ubuntu 20.04 or later. If your runner image is older than that, the failure will come from the Qt package rather than from the action, which makes it worth checking your runner image first.

Host, target and architecture are three separate decisions

The action asks you to think about three axes, and the documentation is unusually clear about the distinction between the first two. The host is the platform your application builds on, not the platform it runs on. The target is the platform you are building for. The arch is the target architecture or build variant.

The host values are windows, windows_arm64, mac, linux, linux_arm64 and all_os. The all_os value is used for WASM and Android targets from Qt 6.7.0 onward, and it is incompatible with aqtinstall older than 3.2.0. The default host is all_os when the target is android or wasm and the resolved Qt version is 6.7.0 or newer and aqtinstall is 3.2.0 or newer, and otherwise the platform the action is running on.

The target values are desktop, android, ios and wasm, defaulting to desktop. The target should be set when building for iOS or Android, and there are hard host constraints: iOS builds are supported only on macOS hosts, and Win RT builds only on Windows hosts.

The architecture mapping is the most useful part of the documentation, because it is the part you would otherwise have to discover by trial and error. For a Linux x64 host with a desktop target the arch is linux_gcc_64 on Qt 6.7 and newer, and gcc_64 before that. For macOS it is clang_64, and for macOS with an iOS target it is ios. For Windows x64 hosts the mapping walks back through compiler generations, win64_msvc2022_64 on Qt 6.8 and newer, win64_msvc2019_64 from 5.15 to 5.8, win64_msvc2017_64 from 5.9 to 5.15, win64_msvc2015_64 from 5.6 to 5.9, and win64_msvc2013_64 below 5.6.

Linux x86 has no prebuilt package, and the action says so

One limitation is stated in bold in the documentation, and it is the one to check first if you are on Linux. Linux x86 packages are not supported by the action, because Qt does not offer pre-built Linux x86 packages. The suggested alternatives are to use your distribution's repository or to build from source manually.

That is a real gap, and it is structural rather than a limitation of this particular action. A prebuilt package has to be published by someone, and the 32-bit Linux desktop packages simply do not exist in the Qt distribution for this action to fetch.

The same shape of constraint appears elsewhere. The wasm target is used together with the all_os host value and is incompatible with aqtinstall older than 3.2.0, so an older toolchain in the runner and a WASM build are mutually exclusive.

The action also points to an external list of architectures, describing it as a way to find the full list of architectures easily, which is the reference to consult when your build matrix needs a variant the default mapping does not cover.

Commercial Qt needs aqtinstall 3.2.1 and your own credentials

There is a second path through the action, for people with a commercial Qt licence, and it works quite differently. The use-official option, available since v4.2, decides whether aqtinstall is used to install Qt with the official online installer, which is what enables the commercial versions for those owning a licence. It is incompatible with aqtinstall older than 3.2.1.

Two consequences follow. The host parameter is then ignored, because commercial Qt versions can only be installed on the operating system running the installer. And credentials are required, with the email and pw fields passed to authenticate with the Qt servers. Both fields should be stored as secrets, and the documentation suggests QT_EMAIL and QT_PW as the secret names, with the example showing them referenced as secrets rather than written inline.

    - name: Install Qt
      uses: jurplel/install-qt-action@v4
      with:
        version: '6.8.3'
        target: 'desktop'
        arch: 'win64_msvc2022_64'
        use-official: true
        email: ${{ secrets.QT_EMAIL }}
        pw: ${{ secrets.QT_PW }}

The default for use-official is false, so the open source path is what you get without asking for anything.

Install dir, dependency installation, modules and archives

Four smaller options decide what lands on the runner and how much of it there is.

The dir option sets the directory prefix Qt is installed to. The documentation gives the worked example: setting dir to ${{ github.workspace }}/example/ puts the bin folder at $GITHUB_WORKSPACE/example/Qt/5.15.2/{arch}/bin. The recommendation is to access the Qt directory through the QT_ROOT_DIR environment variable, which points at $GITHUB_WORKSPACE/example/Qt/5.15.2/{arch} in that example, rather than hard-coding the path. The default is $RUNNER_WORKSPACE, one folder above the starting directory.

The install-deps option controls whether Qt's Linux dependencies are installed automatically through apt. It can be set to nosudo to stop the action using sudo, which the documentation suggests for a docker container where the user already has sufficient privileges. The default is true.

The modules option takes a whitespace delimited list of addon modules to install, with the possible values including qtcharts, qtdatavis3d, qtpurchasing, qtvirtualkeyboard, qtwebengine, qtnetworkauth, qtwebglplugin, qtscript and debug_info. The archives option takes a list of Qt archives to install, with qtbase, qtsvg, qtdeclarative, qtgamepad, qtgraphicaleffects, qtimageformats and qtlocation named. Both default to none.

The archives option carries a strong warning. The documentation says to read the aqtinstall documentation before using it, and calls it typically unnecessary unless you are aiming for a bare minimum installation. That is good advice, because trimming the archive set is the fastest way to end up with a Qt install that cannot build your project.

Caching, Python setup and the self-hosted runner caveat

Caching is off by default, and the semantics are worth understanding before you turn it on. When cache is set to true, Qt will not be downloaded if a cached version is available, but the environment variables will still be set and the essential build tools will still be installed. So the cache saves the download, not the setup. The cache-key-prefix option controls the key and defaults to install-qt-action.

The last option is setup-python, and it exists for a specific situation. Setting it to false skips the use of setup-python to find or download a valid Python version. The documentation says that on a self-hosted runner you will probably need to set this to false, since the action otherwise expects to be able to locate or fetch a Python it is happy with.

That is the whole option surface, and it is worth noting what is not here. There is no option for a proxy or a mirror, no option for a specific aqtinstall version, and no option for installing a compiler or a build system, so the action assumes the runner image already has a working toolchain for the platform you chose. The Linux x86 exclusion and the host constraints for iOS and Win RT are the two places where that assumption breaks, and they are both documented.

Editorial conclusion

Adopt install-qt-action if you build Qt projects on GitHub Actions and want the toolchain, the architecture mapping and the caching handled for you instead of by a shell script in your workflow. Do not adopt it if you build for Linux x86, since the action states that Qt does not offer pre-built Linux x86 packages and points you at your distribution repository or a source build instead. Before you wire it in, check three things: the host and target combination, since iOS builds only run on macOS hosts and Win RT builds only on Windows hosts, the aqtinstall version, because the all_os host value and the commercial installer both require aqtinstall 3.2.0 or newer, and whether the default version 6.8.3 matches the Qt release your project pins against.

Frequently asked questions

Official sources

1. Issues
2. jurplel/install-qt-action on GitHub
3. License: MIT
4. README
5. Releases