qtchooser

List available Qt versions from the configuration files

$ qtchooser --list-versions

$ qtchooser --print-env

$ qtchooser --run-tool=[tool] --qt=[version_name]

$ qtchooser --install [version_name] [path/to/qmake]

$ qtchooser --help

qtchooser [OPTIONS] [COMMAND [ARGS...]]

-qt=QtVersion
    Specifies which Qt version to use. Common values include version numbers (e.g., '5', '6'), specific aliases (e.g., 'qt515', 'qt62'), or 'default' to use the system default configuration.

-run-script
    If the COMMAND is a script, this option ensures it is executed properly after setting up the environment, rather than being treated as a binary executable.

-list-versions
    Lists all available Qt versions that qtchooser can detect based on its configuration files.

-print-env
    Prints the environment variables (e.g., PATH, QT_INSTALL_LIBS) that would be set for the chosen Qt version, without executing any command. Useful for debugging.

-help, --help
    Displays a help message and exits.

-version, --version
    Displays version information about qtchooser and exits.

qtchooser is a utility designed to help developers manage multiple Qt installations on a single system. It acts as a wrapper around Qt command-line tools (such as qmake, moc, uic, rcc, etc.) by setting the necessary environment variables (like PATH, QT_INSTALL_LIBS, QT_INSTALL_HEADERS) to point to a specific Qt version. This allows users to easily switch between different Qt major or minor versions (e.g., Qt5, Qt6, or specific patch versions) without manually modifying system paths or rebuilding projects. It achieves this by reading configuration files, typically located in /etc/xdg/qtchooser and ~/.config/qtchooser, which map user-friendly version names to actual installation paths. When a command is invoked via qtchooser, it ensures that the correct Qt binaries and libraries are found, streamlining cross-version development and testing.

qtchooser relies on configuration files (e.g., .conf files in /etc/xdg/qtchooser and ~/.config/qtchooser) to define Qt version paths. If these files are incorrect, missing, or do not point to valid Qt installations, qtchooser may not function as expected or might fail to find the desired Qt version. The QT_SELECT environment variable takes precedence over command-line arguments, potentially overriding the selected Qt version. While it manages the environment for command-line tools, it doesn't directly influence how already compiled applications link against Qt libraries unless specifically designed to do so.

If the QT_SELECT environment variable is set, it overrides any -qt option passed to qtchooser. This variable specifies the desired Qt version (e.g., export QT_SELECT=qt6). It is particularly useful for persistent selection within a shell session, build scripts, or CI environments, ensuring that all subsequent Qt command-line tool invocations use the specified version without needing to explicitly pass the -qt flag.

qtchooser discovers available Qt versions by reading .conf files. These files are typically located in /etc/xdg/qtchooser/ for system-wide configurations and ~/.config/qtchooser/ for user-specific overrides. Each .conf file defines a Qt version alias and its corresponding binary path. For example, a file named qt6.conf might contain the path /opt/Qt/6.x.x/gcc_64/bin, allowing users to select this version simply by using -qt=qt6.

qtchooser was introduced to address the growing need for developers to manage multiple Qt installations side-by-side on a single development machine. Prior to its existence, switching between different Qt major or minor versions for command-line build tools (like qmake) often involved cumbersome manual adjustments to the system's PATH environment variable or the use of custom wrapper scripts. This process was prone to errors and inefficiencies. qtchooser streamlined this workflow by providing a standardized and easy-to-use mechanism to select the desired Qt environment for development and build tasks, significantly improving the developer experience for cross-version Qt development and testing.

qmake(1), moc(1), uic(1), rcc(1), qtpaths(1), update-alternatives(8)