{"id":6309,"library":"aqtinstall","title":"aqtinstall: Unofficial Qt Installer","description":"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.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/miurahr/aqtinstall","tags":["qt","installer","development-tools","cross-platform","ci-cd"],"install":[{"cmd":"pip install aqtinstall","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or higher.","package":"python","optional":false}],"imports":[{"symbol":"AqtInstaller","correct":"from aqtinstall.aqt import AqtInstaller"},{"note":"The core installation function is located within the `aqtinstall.aqt` module, not directly under `aqtinstall`.","wrong":"from aqtinstall import run_install","symbol":"run_install","correct":"from aqtinstall.aqt import run_install"}],"quickstart":{"code":"import os\nfrom aqtinstall.aqt import run_install\n\n# Define installation parameters\nqt_version = '6.5.0'\nos_name = 'linux'\narch = 'gcc_64' # Example for Linux; 'win64_msvc2019_64' for Windows, 'macos' for macOS\nmodules = ['qtcharts', 'qtlottie'] # Optional: specific modules\ninstall_dir = os.path.join(os.environ.get('HOME', '.'), 'qt_test_install')\n\nprint(f\"Attempting to install Qt {qt_version} for {os_name}/{arch} into {install_dir}\")\n\ntry:\n    run_install(\n        tool='qt',\n        version=qt_version,\n        os_name=os_name,\n        arch=arch,\n        output_dir=install_dir,\n        modules=modules,\n        # For commercial Qt versions, specify an account:\n        # username=os.environ.get('QT_ACCOUNT_USERNAME', ''),\n        # password=os.environ.get('QT_ACCOUNT_PASSWORD', ''),\n        # Use dry_run=True to test parameters without downloading\n        # dry_run=True\n    )\n    print(f\"Qt {qt_version} successfully installed to {install_dir}\")\nexcept Exception as e:\n    print(f\"Error during Qt installation: {e}\")\n    print(\"Please check your OS, architecture, Qt version, network, and permissions.\")\n\n# Example of using AqtInstaller class (more granular control)\n# installer = AqtInstaller(ArchivesPath(qt_version, os_name, arch, tool='qt'))\n# installer.install(install_dir, modules=modules)\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or higher. `aqtinstall` now requires `Python >= 3.9`.","message":"Support for Python 3.7 was dropped in `aqtinstall` version 3.1.16. Older Python versions will no longer work.","severity":"breaking","affected_versions":"<3.1.16"},{"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).","message":"The combination of Qt version, OS, and architecture must be correct and available on Qt's servers. Incorrect combinations will lead to download failures.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your environment has stable internet access. For CI/CD, consider caching strategies or pre-downloading if network is a concern.","message":"An active internet connection is required for `aqtinstall` to download Qt packages. Large Qt installations can consume significant bandwidth and time.","severity":"gotcha","affected_versions":"all"},{"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`.","message":"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.","severity":"breaking","affected_versions":"<3.2.0"},{"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`.","message":"The `output_dir` specified for installation must have appropriate write permissions for the user running `aqtinstall`.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}