aqtinstall: Unofficial Qt Installer

3.3.0 · active · verified Wed Apr 15

aqtinstall is a Python library and command-line tool for installing specific versions of Qt, Qt tools, and add-ons directly from Qt's official servers. It provides an unofficial, robust, and programmatic way to manage Qt installations, particularly useful in CI/CD environments. The current version is 3.3.0, and it generally follows a monthly or bi-monthly release cadence for minor updates and bug fixes.

Warnings

breaking Support for Python 3.7 was dropped in `aqtinstall` version 3.1.16. Older Python versions will no longer work.
Fix: Upgrade your Python environment to 3.9 or higher. `aqtinstall` now requires `Python >= 3.9`.
gotcha The combination of Qt version, OS, and architecture must be correct and available on Qt's servers. Incorrect combinations will lead to download failures.
Fix: Consult the official Qt download archives or `aqtinstall`'s `list-archives` command (via CLI) to verify available options for your desired Qt version and platform. Common architectures include `win64_msvc2019_64`, `linux_gcc_64`, `macos` (for macOS universal builds).
gotcha An active internet connection is required for `aqtinstall` to download Qt packages. Large Qt installations can consume significant bandwidth and time.
Fix: Ensure your environment has stable internet access. For CI/CD, consider caching strategies or pre-downloading if network is a concern.
breaking Support for commercial Qt versions requires `aqtinstall` version 3.2.0 or newer. Older versions will not correctly handle authentication or installation of commercial Qt.
Fix: Upgrade `aqtinstall` to version 3.2.0 or higher. When installing commercial Qt, provide your Qt account username and password via `username` and `password` parameters to `run_install` or `AqtInstaller`.
gotcha The `output_dir` specified for installation must have appropriate write permissions for the user running `aqtinstall`.
Fix: Ensure the target directory is writable. For system-wide installations, you might need `sudo` or administrator privileges, or choose a user-specific location like `~/.local/Qt`.

Install

pip install aqtinstall Install latest version

Imports

AqtInstaller
```
from aqtinstall.aqt import AqtInstaller
```
run_install
```
from aqtinstall.aqt import run_install
```
The core installation function is located within the `aqtinstall.aqt` module, not directly under `aqtinstall`.

Quickstart

This quickstart demonstrates how to programmatically install a specific Qt version and optional modules using `aqtinstall.aqt.run_install`. It sets up an installation directory and handles potential errors. Remember to adjust `os_name` and `arch` to match your target system. For commercial Qt versions, you might need to provide username and password as environment variables or directly.

import os
from aqtinstall.aqt import run_install

# Define installation parameters
qt_version = '6.5.0'
os_name = 'linux'
arch = 'gcc_64' # Example for Linux; 'win64_msvc2019_64' for Windows, 'macos' for macOS
modules = ['qtcharts', 'qtlottie'] # Optional: specific modules
install_dir = os.path.join(os.environ.get('HOME', '.'), 'qt_test_install')

print(f"Attempting to install Qt {qt_version} for {os_name}/{arch} into {install_dir}")

try:
    run_install(
        tool='qt',
        version=qt_version,
        os_name=os_name,
        arch=arch,
        output_dir=install_dir,
        modules=modules,
        # For commercial Qt versions, specify an account:
        # username=os.environ.get('QT_ACCOUNT_USERNAME', ''),
        # password=os.environ.get('QT_ACCOUNT_PASSWORD', ''),
        # Use dry_run=True to test parameters without downloading
        # dry_run=True
    )
    print(f"Qt {qt_version} successfully installed to {install_dir}")
except Exception as e:
    print(f"Error during Qt installation: {e}")
    print("Please check your OS, architecture, Qt version, network, and permissions.")

# Example of using AqtInstaller class (more granular control)
# installer = AqtInstaller(ArchivesPath(qt_version, os_name, arch, tool='qt'))
# installer.install(install_dir, modules=modules)

view raw JSON →