通过命令行界面获取并安装 Qt
使用命令行界面配合Qt Online Installer 和Qt Maintenance Tool 来安装、卸载、更新和搜索组件。
命令行界面同时支持交互式和非交互式（无人值守）使用。以下主题提供了有关如何使用命令行界面的示例和信息：
- 使用命令行界面下载Qt Online Installer
- 安装组件名称
- 无需用户交互的安装
- 需要用户交互的安装
- 卸载软件包
- 列出已安装的软件包
- 检查更新
- 更新软件包
- 常用命令
- 为 Opensource 选择镜像
- 命令行界面使用总结
使用命令行界面下载Qt Online Installer
您可以在命令行界面中使用 `curl ` 命令下载Qt Online Installer 。要查看适用于不同平台的所有Qt Online Installer 软件包，请访问Qt Online Installer official releases。
若要下载与远程文件同名的特定Qt Online Installer 软件包，请使用-O （大写字母“O”）选项。
以下示例命令用于下载qt-online-installer-linux-x64-online.run 软件包：
curl -OL https://download.qt.io/official_releases/online_installers/qt-online-installer-linux-x64-online.run安装组件名称
使用别名软件包进行快速安装
您无需搜索特定的软件包名称进行安装，而是可以使用别名软件包来安装最常见的配置。别名软件包是一种快捷方式，可包含实际的软件包，从而提供更便捷的安装体验。
列出现有的别名软件包
要在命令行界面中列出现有的别名包，请使用以下命令。
使用Qt Online Installer ：
<installer executable> search有关 Qt Online Installer 不同平台的可执行文件，请参阅“通过用户交互进行安装”。
使用Qt Maintenance Tool ：
<maintenancetool executable> search有关 Qt Maintenance Tool 不同平台的可执行文件，请参阅“需要用户交互的安装”。
别名包的内容
别名包的内容列于下表中。
注意： 下文列出的别名包示例均基于Qt 6.12.0 版本。请务必使用与您当前所用 Qt 版本相匹配的包。
| 别名包名称 | Qt Online Installer （包内容） |
|---|---|
| qt6.12.0-essentials |
|
| qt6.12.0-essentials-dev |
|
| qt6.12.0-full | |
| qt6.12.0-full-dev | |
| qt6.12.0-full-dbg | |
| qt6.12.0-sdk |
|
Qt Online Installer 命令示例
# Windows: new installation with Qt Online Installer
qt-unified-windows-x64-[Qt Online Installer version]-online.exe install qt6.12.0-sdk
# macOS: new installation with Qt Online Installer
hdiutil attach qt-unified-macOS-x64-[Qt Online Installer version]-online.dmg
/Volumes/qt-unified-macOS-x64-[Qt Online Installer version]-online/qt-unified-macOS-x64-[Qt Online Installer version]-online.app/Contents/MacOS/qt-unified-macOS-x64-[Qt Online Installer version]-online install qt6.12.0-sdk
hdiutil detach /Volumes/qt-unified-macOS-x64-[Qt Online Installer version]-online
# Linux: new installation with Qt Online Installer
qt-unified-linux-x64-[Qt Online Installer version]-online.run install qt6.12.0-sdkWindows 系统的别名包选项
注意： 本节中的信息 适用于 Qt 6.8、Qt 6.9 和 Qt 6.10 版本。
ARM64 版 Windows
仅安装 MSVC 二进制文件（msvc2022-arm64），因为其他 Qt 二进制软件包在 Windows on ARM（WoA）上不可用。
基于 x86_64 的 Windows
默认情况下，仅安装 MinGW 二进制文件。
不过，在基于 x86_64 的 Windows系统上，您还可以安装以下工具链的二进制文件。
- llvm-mingw
- msvc2022
- msvc2022-arm64（用于交叉编译）
例如，使用qt6.12.0-essentials别名包会使用默认的 MinGW 二进制文件安装该包。
若要获取包含（例如）MSVC 2022 二进制文件的 `Qt essentials ` 包内容，请使用相应的 `qt6.12.0-msvc2022-essentials` 别名包。
列出非别名包
要列出非别名包，请在命令行界面中使用以下命令。
使用 `Qt Online Installer`：
<installer executable> search --type package有关 Qt Online Installer 不同平台的可执行文件，请参阅《通过用户交互进行安装》。
使用Qt Maintenance Tool ：
<maintenancetool executable> search --type package有关 Qt Maintenance Tool 不同平台的可执行文件，请参阅“需要用户交互的安装”。
高级搜索特定安装包
使用search 命令和正则表达式搜索可用软件包： search <regexp>。您可以使用 --filter-packages <regexp>。例如，根据显示名称信息进行筛选可帮助搜索。
例如，以下命令可查找所有适用于 Qt 6.12.0 的 MSVC 2022 软件包：
search .*6120.*msvc2022如果您按以下方式过滤搜索结果，将获得相同的结果：
search --filter-packages DisplayName=MSVC 2022,Version=6.12.0最终，您将获得以下软件包：
<availablepackages>
<package name="qt.qt6.6120.win64_msvc2022_64" displayname="MSVC 2022 64-bit" version="6.12.0.-0-<timestamp>"/>
<package name="qt.qt6.6120.win64_msvc2022_arm64" displayname="MSVC 2022 ARM64" version="6.12.0.-0-<timestamp>"/>
</availablepackages>当您搜索某个包所支持的所有 Qt 版本时，也可以使用筛选功能。例如，搜索所有适用于 Qt 版本的Qt Charts 包：
search --filter-packages DisplayName=charts搜索结果如下：
<availablepackages>
<package name="qt.qt5.5125.qtcharts" displayname="Qt Charts" version="5.12.5-0-<timestamp>"/>
<package name="qt.qt6.641.addons.qtcharts" displayname="Qt Charts" version="6.4.1-0-<timestamp>"/>
<package name="qt.qt5.5123.qtcharts" displayname="Qt Charts" version="5.12.3-0-<timestamp>"/>无需用户干预的安装
默认情况下，Qt Online Installer 或Qt Maintenance Tool 在安装过程中可能会要求提供额外信息，这需要用户关注。通过命令行界面，若预先使用相应选项提供所有所需信息，即可实现无人值守安装。
使用Qt Online Installer
您可以按照以下步骤通过命令行界面进行无需用户交互的新安装：
- 定义 Qt Online Installer 可执行文件。
- 使用
--root。 - 使用
install <list of packages>命令并配合无人值守使用选项。请参阅“无人值守使用选项”中的完整选项列表。
以下示例演示了如何使用Qt Online Installer 在Windows、macOS和Linux系统上安装Qt 6.12.0二进制文件。无人值守命令会自动接受许可协议（--accept-licenses），对所有提示信息均以默认答案作答（--default-answer），并跳过继续执行操作的权限请求（--confirm-command）：
# Windows: new installation with Qt Online Installer
qt-unified-windows-x64-[Qt Online Installer version]-online.exe --root C:\Users\[username]\installation_dir --accept-licenses --default-answer --confirm-command install qt.qt6.6120.win64_msvc2022_64
# macOS: new installation with Qt Online Installer
qt-unified-macOS-x64-[Qt Online Installer version]-online.dmg --root /home/<username>/installation_dir --accept-licenses --default-answer --confirm-command install qt.qt6.6120.clang_644
# linux: new installation with Qt Online Installer
qt-unified-linux-x64-[Qt Online Installer version]-online.run --root /home/<username>/installation_dir --accept-licenses --default-answer --confirm-command install qt.qt6.6120.linux_gcc_64“无人值守使用选项”列出了所有可用的无人值守使用选项。
使用Qt Maintenance Tool
您可以按照以下步骤，通过命令行界面在无需用户交互的情况下更新现有安装：
- 定义 Qt Maintenance Tool 可执行文件。
- 使用
install <list of packages>并配合无人值守使用选项。完整的选项列表请参阅“无人值守使用选项”。
以下示例演示了如何在 Windows、macOS 和 Linux 上使用 `Qt Maintenance Tool ` 将 Qt 6.12.0 二进制文件添加到现有安装中。无人值守命令会自动接受许可协议（--accept-licenses），对所有消息查询均使用默认答案（--default-answer），并跳过继续执行操作的权限提示（--confirm-command）：
# Windows: update installation with Qt Maintenance Tool
MaintenanceTool.exe --accept-licenses --default-answer --confirm-command install qt.qt6.6120.win64_msvc2022_64
# macOS: update installation with Qt Maintenance Tool
MaintenanceTool.app/Contents/MacOS/MaintenanceTool --accept-licenses --default-answer --confirm-command install qt.qt6.6120.clang_64
# linux: update installation with Qt Maintenance Tool
MaintenanceTool.run --accept-licenses --default-answer --confirm-command install qt.qt6.6120.linux_gcc_64无人值守使用选项
下表列出了无人值守命令行使用的所有选项：
| 无人值守模式选项 | 描述 |
|---|---|
--accept-licenses | 自动接受所有许可协议。 |
--accept-obligations | 在开源安装中，无需用户输入即可接受 Qt 开源使用条款。 |
--default-answer | 对所有消息查询均使用默认答案进行回复。 |
--auto-answer <identifier=value> | 如果您希望对某些查询给出不同的回答，可以使用此选项。例如：--auto-answer telemetry-question=Yes,AssociateCommonFiletypes=Yes 。请参阅“--auto-answer 的消息标识符”中列出的所有消息标识符。 |
--accept-messages | 接受所有消息查询。 |
--reject-messages | 拒绝所有消息查询。 |
--confirm-command | 默认情况下，Qt Online Installer 和Qt Maintenance Tool 会打印受此选项影响的组件摘要。然后，它们会请求继续操作的许可，以防止意外更改。此选项将跳过请求继续操作的许可。 |
--email <your_email> | 在从命令行登录时提供电子邮件地址。有关详细信息，请参阅“提供登录信息”。 |
--pw <your_pw> | 在通过命令行登录时提供密码。有关详细信息，请参阅“提供登录信息”。 |
--file-query <identifier=value> | 有时Qt Online Installer 会要求提供文件或文件夹的位置。您可以使用--file-query <identifier=value> 提供该位置。例如：--file-query PathForSDP7=<path_to_sdp> 。这些标识符会在实际问题和消息类型之前显示在命令行中。您可以从那里获取这些标识符。 |
--auto-answer 的消息标识符
使用--auto-answer 选项为特定查询提供答案。下表列出了--auto-answer 中已知的标识符及其对应值：
| ID | 值 | 默认值 |
|---|---|---|
| 操作不存在错误 | 中止、忽略 | 忽略 |
| 覆盖目标目录 | 是，否 | 否 |
| 为更新停止进程 | 重试、忽略、取消 | 取消 |
| 安装错误并取消 | 重试、忽略、取消 | 取消 |
| 安装错误（忽略） | 重试、忽略 | 忽略 |
| 关联常见文件类型 | 是，否 | 是 |
| 遥测问题 | 是，否 | 是 |
提供登录信息
Qt Online Installer 以及Qt Maintenance Tool 均采用强制登录机制。若缓存中存在qtaccount.ini文件，则强制登录会使用该文件中的信息。您可通过以下方式找到qtaccount.ini：
| 主机 | qtaccount.ini 位置 |
|---|---|
| Windows | C:\Users\<username>\AppData\Roaming\Qt |
| macOS | /Users/<username>/Library/Application Support/Qt/qtaccount.ini |
| Linux | /home/<username>/.local/share/Qt/qtaccount.ini |
此外，您还可以通过命令行使用电子邮件和密码参数登录：--email <your_email> 和--pw <your_pw> 。
此外，您还可以将 JWT 令牌保存到环境变量QT_INSTALLER_JWT_TOKEN 中。该令牌可在qtaccount.ini文件中找到。
需要用户交互的安装
您可以按照以下方式使用需要用户交互的命令行界面：
- 定义可执行文件：
- Qt Online Installer 如果您需要进行新安装。
- Qt Maintenance Tool 如果您需要更新现有安装。
- 进行新安装时，请使用以下命令指定安装目录：
--root - 使用
install <list of packages>来安装所列的软件包。
以下示例演示了如何使用Qt Online Installer 在Windows、macOS和Linux上新建Qt 6.12.0二进制文件安装：
# Windows: new installation with user interaction
qt-unified-windows-x64-[Qt Online Installer version]-online.exe --root C:\Users\[username]\installation_dir install qt.qt6.6120.win64_msvc2022_64
# macOS: new installation with user interaction
qt-unified-macOS-x64-[Qt Online Installer version]-online.dmg --root /home/<username>/installation_dir install qt.qt6.6120.clang_64
# linux: new installation with user interaction
qt-unified-linux-x64-[Qt Online Installer version]-online.run --root /home/<username>/installation_dir install qt.qt6.6120.linux_gcc_64以下示例演示了如何通过Qt Maintenance Tool 安装Qt 6.12.0二进制文件来更新现有安装：
# Windows: update installation with Qt Maintenance Tool
MaintenanceTool.exe install qt.qt6.6120.win64_msvc2022_64
# macOS: update installation with Qt Maintenance Tool
MaintenanceTool.dmg install qt.qt6.6120.clang_64
# Linux: update installation with Qt Maintenance Tool
MaintenanceTool.run install qt.qt6.6120.linux_gcc_64卸载软件包
命令行界面提供了两个用于卸载软件包的命令：
-
remove <list of packages>命令将卸载所列的软件包。 - 该
purge命令用于卸载所有已安装的软件包。
您应将这两个命令与Qt Maintenance Tool 配合使用。
默认情况下，Qt Maintenance Tool 会显示受该命令影响的组件摘要。随后，该工具会请求许可以继续操作，以防止意外更改。使用 --confirm-command 可跳过继续操作的权限提示。
以下示例将在无需用户交互的情况下卸载 Qt 6.12.0 二进制文件：
# windows
MaintenanceTool.exe --confirm-command remove qt.qt6.6120.win64_msvc2022_64
# macOS
MaintenanceTool.dmg --confirm-command remove install qt.qt6.6120.clang_64
# linux
MaintenanceTool.run --confirm-command remove qt.qt6.6120.linux_gcc_64以下示例将卸载所有软件包，并请求用户许可以继续执行操作：
# Windows
MaintenanceTool.exe purge
# macOS
MaintenanceTool.dmg purge
# Linux
MaintenanceTool.run purge列出已安装的软件包
使用 list 命令可列出您已安装的所有软件包。请按以下方式使用该命令并指定Qt Maintenance Tool 参数：
# Windows
MaintenanceTool.exe list
# macOS
MaintenanceTool.dmg list
# Linux
MaintenanceTool.run list检查更新
该 check-updates 该命令用于检查已安装软件包的可用更新。请按以下方式结合Qt Maintenance Tool 使用该命令：
# Windows
MaintenanceTool.exe check-updates
# macOS
MaintenanceTool.dmg check-updates
# Linux
MaintenanceTool.run check-updates更新软件包
该 update 命令用于更新已安装的软件包。请在Qt Maintenance Tool 中按以下方式使用该命令：
# windows
MaintenanceTool.exe update
# macOS
MaintenanceTool.dmg update
# linux
MaintenanceTool.run update常用命令
使用 <installer_executable> --help 可查看可用的命令和选项。常用命令如下：
| 命令 | 用法 |
|---|---|
in,install <pkg ...> | 安装作为参数指定的软件包。如果未指定任何软件包，则安装默认软件包集。 |
rm,remove <pkg ...> | 卸载选定的软件包及其子组件。 |
ch,check-updates | 显示Qt Maintenance Tool 上可用的更新信息。 |
up,update <pkg ...> | 更新作为参数指定的软件包。如果未指定软件包，则安装所有可用的更新。 |
se,search <regexp> | 搜索可用的软件包。如果未指定任何搜索模式，则显示所有可用的软件包。您可以使用--filter-packages 选项为搜索操作指定额外的过滤条件。请参阅Qt Installer Framework 手册中的“选项摘要”。 |
Qt Installer Framework 手册中提供了有关命令和选项的更多信息。
为 Opensource 选择镜像
Qt Online Installer 提供了一个选项，用于为开源元数据和下载选择镜像。可通过命令行使用 --mirror 选项在命令行中设置镜像。
例如，请按以下方式使用--mirror ：
installer(.exe) --mirror http://www.nic.funet.fi/pub/mirrors/download.qt-project.org
installer(.exe) --mirror http://ftp2.nluug.nl/languages/qt
maintenancetool(.exe) --mirror http://qt.mirror.constant.com如示例所示，请勿使用完整路径，而应使用“/online”之前的路径（末尾不带正斜杠）。
您可以在https://download.qt.io/online/qtsdkrepository/windows_x86/root/qt/Updates.xml.mirrorlist 上查看可用的镜像站点。
命令行接口使用概要
Qt Installer Framework 手册中提供了有关命令行接口的更多详细信息：
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
