How to Install Qt on Linux: A Practical Guide

Install Qt on Linux to build and run applications that use the Qt framework, or to work with them in Qt Creator. The most straightforward route is the official Qt Online Installer, which lets you choose a Qt version and development tools; you will need an internet connection and permission to install software for your account.

What You’ll Need

A supported Linux desktop and an internet connection. The installer is a graphical application, so use a desktop session rather than a text-only terminal.
A user account with permission to write to your home directory. Installing Qt there usually does not require administrator access.
A C++ compiler and build tools if you plan to compile C++ projects. On Ubuntu or Debian, these are commonly installed with sudo apt install build-essential; on Fedora, use sudo dnf install gcc-c++ make. Package names can vary by release.
Enough disk space for the selected Qt version, modules, and optional examples. The required space varies considerably, so check the installer’s estimate and leave room for project builds.

Step-by-Step

Choose how to install Qt. For a general-purpose development setup, use the official Qt Online Installer. It can install Qt libraries, Qt Creator, and additional components together. Linux distributions also provide Qt packages, which are convenient for system software or a quick start, but may offer a different version or omit tools you want. Avoid mixing distribution Qt packages and a separate Qt installation without a specific reason.
Get the installer from Qt’s official website. Open the Qt download page and select the Linux Online Installer. The download is a self-extracting installer file, typically with a name ending in .run. Save it somewhere you can find, such as ~/Downloads. Sign in or create a Qt account if the installer asks; access and account requirements can change, so follow the current prompts.
Make the downloaded file executable. Open a terminal and move to the download folder, for example with cd ~/Downloads. Use ls to check the exact filename, then run chmod +x ./installer-file.run, replacing the example name with the actual one. This gives your user permission to run the file; it does not install Qt or require a system-wide permission change.
Start the installer. Run it from the same folder with ./installer-file.run. If your desktop file manager offers an “Run” or “Execute” option for downloaded programs, that may work too. Do not use sudo by default: installing into your home directory avoids unnecessary administrator access and makes updates easier to manage.
Sign in and select an installation location. Follow the on-screen prompts. Choose a folder you own and can write to, such as a Qt directory in your home folder. Keep the path straightforward; spaces and unusual characters can complicate some build configurations. If the installer offers to remember the location, note it for later.
Select the components you need. Expand the Qt version you intend to use and select a desktop kit matching your system, such as the Linux desktop option for the compiler available on your machine. Select Qt Creator if you want Qt’s integrated development environment. Add only modules, examples, and debugging tools you need; extra components consume disk space and can lengthen installation and updates. Do not select a mobile or embedded target unless you have the corresponding development setup.
Review and install. Check the selected version, desktop kit, and destination before confirming. Let the installer download and install the files. Keep the installer open until it reports completion. If a download fails, retry on a stable connection; a corporate proxy or firewall may need configuration through your network settings.
Open Qt Creator and configure a kit. Launch Qt Creator from your desktop’s application menu or from the installation directory. A kit connects a Qt version to a compiler, debugger, and build tool. Open the kits or preferences settings and check that a desktop kit is detected and marked usable. If no kit is available, install the compiler and build tools for your distribution, then restart Qt Creator and check again.
Verify the installation with a small project. In Qt Creator, create a simple Qt Widgets or Qt Quick project using a template that matches the components you installed. Select the desktop kit, build, and run it. A successful build and launch confirms more than merely seeing the Qt Creator window: it checks that Qt, the compiler, and the build configuration can work together.

Common Mistakes

Running the installer as root. Using sudo can create root-owned files in your home directory and make later updates difficult. Use a user-writable installation folder unless you specifically need a managed, shared system installation.
Installing Qt Creator but not a Qt desktop kit. The IDE is not the same as the Qt libraries or compiler. Confirm that you selected a Qt version and a compatible desktop component in the installer.
Choosing the wrong compiler kit. A kit for a different compiler or target cannot necessarily build your Linux desktop application. Match the Qt kit to the compiler installed on your system.
Assuming a successful install means every project will build. Projects can depend on additional Qt modules, external libraries, or a particular Qt version. Read the project’s build instructions and install only the missing requirements you can identify.
Mixing installation methods. System packages and the online installer can coexist, but using libraries from one installation with tools from another can lead to confusing paths and version mismatches. Keep a project’s Qt version and kit consistent.

Tips

Write down the Qt version and installation path used by each project. This helps when you return to a project after an update.
Choose the newest Qt version your project supports, rather than assuming the newest available release will be compatible with older code.
Install only the modules you need initially. You can reopen the Qt Maintenance Tool from the installation directory to add, remove, or update components later.
Keep Linux development tools current using your distribution’s package manager. Use the package manager for compilers and system dependencies; use the Qt installer to manage the Qt installation it created.

Troubleshooting

“Permission denied” when launching the installer: Confirm that you used chmod +x on the correct downloaded file and are running it from the right directory. If the file is on a mounted drive that blocks program execution, move it to a location in your home directory and try again.
The installer does not open or shows a missing-library message: Check the message for the named dependency, then install the corresponding runtime package using your distribution’s package manager. Package names differ across distributions; search the distribution’s documentation or package repository rather than downloading random library files.
Qt Creator reports no compiler or kit: Install the C++ compiler and build tools for your distribution, then restart Qt Creator. Check its kit settings to see whether the compiler and Qt version are detected. If necessary, select the correct compiler and Qt installation in the kit configuration.
A project builds but will not start: Check the application output for missing shared libraries or Qt plugins. Confirm that you are launching the build made with the selected kit and that the project’s required Qt modules are installed. For a project you downloaded, follow its own run instructions.
Downloads fail or installation stops midway: Retry with a stable connection and check available disk space. If you are behind a proxy, configure the installer or network environment to use it. Reopen the installer or Maintenance Tool and repair or resume the installation if that option is offered.
The distribution’s Qt version is not the one you expected: Package repositories may intentionally provide a version suited to that distribution’s release. Check the installed version with the relevant Qt tools, or use the official installer when you specifically need another supported version.

Frequently Asked Questions

Can I install Qt on Linux without Qt Creator?
Yes. In the component selection screen, choose the Qt libraries and development kit you need and leave Qt Creator unselected. You can use another editor and build system.

Do I need to use the terminal?
Not for every step: the installer is graphical. A terminal is useful for making the downloaded installer executable, installing compiler packages, and checking build output.

Is Qt free to use?
Qt has open-source and commercial licensing options. Which terms apply depends on the Qt components and how you use or distribute your application. Review the current license information for your project.

Can I install more than one Qt version?
Yes. The installer can keep multiple versions in separate folders. Select the intended Qt version and matching kit for each project to avoid building against the wrong libraries.

How do I update or remove Qt?
Use the Maintenance Tool in the Qt installation directory to update, add, remove, or uninstall components. For Qt installed through your Linux distribution, manage it with that distribution’s package manager instead.

Should I install Qt from my Linux distribution or from Qt’s website?
Use distribution packages for a convenient, system-managed setup that fits the distribution’s software. Use the official installer when you need to select particular Qt versions, modules, or Qt Creator components.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →