Install Qt and Qt Creator

Summary

• Install via the online installer (recommended)
  1. Download the online installer
  2. Run the online installer
  3. Sign in to your Qt Account
  4. Agree to the open source license
  5. Perform a custom installation
  6. Select Qt components
     • Choosing the prebuilt component
  7. Finish installation
  8. Qt Maintenance Tool
• Install via a package manager (not recommended)
  • Debian-based systems
• Errors and workarounds
  • Qt not found
  • Small icons in Qt Creator on Linux

Install via the online installer (recommended)

This method requires creating an account with Qt. Use the other method if this bothers you.

The advantage of having a Qt Account is that you can use it to report bugs in Qt and leave comments on their tracker. The disadvantage is that you get occasional marketing emails and newsletters, but you can unsubscribe via the link at the bottom of each email.

Download the online installer

Visit https://www.qt.io/download-qt-installer and click "Download" to save the installer on your machine.

You'll only use the installer file once and never again, so there's no need to save it anywhere special.

Run the online installer

Windows

Double-click the installer executable in File Explorer. (You might even be able run or "open" it directly from your web browser.)

macOS

Double-click the .dmg file to open it, then double-click the .app that's inside (no need to drag it to /Applications).

Linux

You need to grant execute permission (a security measure) and then run the installer. You can do this via Terminal:

cd ~/Downloads
chmod +x qt-unified-linux-*-online.run  # grant execute permission
./qt-unified-linux-*-online.run         # execute (run)

Alternatively, right-click on the installer file and go to Properties. Look for Permissions and "Allow file to run as a program" (or similar). Enable that option, then close the Properties dialog and double-click the installer file or run it.

If you get an error along the lines of ./qt-unified-linux-x64-4.4.1-online.run: error while loading shared libraries: libxcb-xinerama.so.0: cannot open shared object file: No such file or directory, you have to install the libxcb-xinerama package:

sudo apt install libxcb-xinerama0

Sign in to your Qt Account

The installer will ask you to log in and you can't skip this part (boo!).

If you don't have a Qt Account you'll need to create one now. You'll be asked for:

• Your email address (must be a real address but not necessarily your primary email)
• A new password to use for your account (write this down or save it in a password manager like Bitwarden)

You will then be asked to check your inbox for a verification email, and given the option to fill in some account details on the Qt website. (They ask for a phone number but you don't have to give this.)

Agree to the open source license

Read the license terms (go on!) and tick the box to say you approve (if you do).

• If you are being paid to use Qt on behalf of a company then you should enter the company's name here.
• Otherwise tick the box to say you are an individual.

Perform a custom installation

Use the default installation folder (unless you have a good reason not to), but make sure you select custom installation. Don't choose a default installation option.

Select Qt components

1. Use the Select Categories filter to display only LTS (Long Term Support) releases.

2. In the tree view, expand the component group named Qt.

3. Expand (don't select) the latest LTS release in the Qt 5 series (currently Qt 5.15.2).

4. From this release, select only two things:

   1. The main prebuilt component for your compiler (see Choosing the prebuilt component below).
   2. Qt Network Authorization (and also Qt WebEngine if building on the 3.x branch).

5. At the bottom of the tree view, expand Developer and Designer Tools.

6. From this component group, select only these things:

   1. Qt Creator (cannot be unselected)
   2. CMake
   3. Ninja
   4. Windows only: If you chose MinGW as the prebuilt component in (4i), select the matching MinGW version here too.

Choosing the prebuilt component

The "prebuilt component" is the actual Qt library. You must choose the one that matches the compiler you will use to build MuseScore.

Linux: Select Desktop gcc 64-bit.

macOS: Select macOS (uses the Clang compiler).

Windows: Select one of the following:

• MSVC (recommended if you already have Visual Studio installed, not VS Code)
• MinGW (recommended if you don't have Visual Studio) At least currently, compiling with MinGW is not possible, you will need to install Visual Studio and use MSVC.

If you pick the prebuilt component for MinGW then remember to install MinGW itself from the "Developer and Designer Tools" section at the bottom of the tree view. It's around 500 MB, but it's much smaller than Visual Studio.

Finish installation

Click Next, accept some more licenses, and then wait while the selected components are downloaded and installed.

Once this is all finished you can delete the online installer (.exe/.dmg/.run file) because you won't need it again.

Qt Maintenance Tool

In future, if you need to update or remove Qt or Qt Creator, or if you want to install different Qt components, this can be done using a program called "Maintenance Tool" that lives in the Qt installation folder. The default location of this tool is:

• Linux and macOS: ~/Qt/MaintenanceTool
• Windows: C:\Qt\MaintenanceTool.exe

The tool should show up in a search for "Maintenance Tool" on Linux or macOS. On Windows, you might want to put a shortcut in your Start menu. To do this, right-click on the file and choose "copy", then go to one of these folders, right-click and choose "Paste shortcut":

• Start menu for all users: %ProgramData%\Microsoft\Windows\Start Menu\Programs
• Start menu just for you: %APPDATA%\Microsoft\Windows\Start Menu\Programs

Install via a package manager (not recommended)

Installing via package manger can be quick and easy. However, the Qt provided by your package manager might be:

• The wrong version of Qt (MuseScore uses Qt 5.15).
• Updated at any time, breaking a build that was previously working.
• Patched (modified) to behave slightly differently compared to upstream Qt.
  • You might encounter bugs not present in the upstream version, which can be hard to pin down.

For these reasons, we recommend that you install Qt via the online installer rather than via a package manager.

Debian-based systems

You can check the available Qt version with:

apt show qtbase5-dev

If your repository has Qt 5.15 or later (not Qt 6), you can install these packages needed to compile MuseScore:

sudo apt install qtbase5-dev qttools5-dev qttools5-dev-tools qtwebengine5-dev \
    qtscript5-dev libqt5xmlpatterns5-dev libqt5svg5-dev libqt5webkit5-dev \
    qtbase5-private-dev libqt5x11extras5-dev qtdeclarative5-dev qtquickcontrols2-5-dev \
    qml-module-qtquick-controls2 qml-module-qtquick-window2 qml-module-qtquick2 \
    qml-module-qtgraphicaleffects qml-module-qtqml-models2 libqt5quicktemplates2-dev \
    qtquickcontrols2-5-dev libqt5x11extras5 libqt5x11extras5-dev libqt5networkauth5 \
    libqt5networkauth5-dev qtbase5-private-dev

To run MuseScore, you will also need:

sudo apt install qml-module-qtquick-dialogs qml-module-qtquick-controls \
    qml-module-qtquick-layouts qml-module-qtquick-window2

TODO: Cover also other distributions which uses different package manager systems. Also give the info command for each package manager so that users can see which version would be installed before actually installing it.

Errors and workarounds

Qt not found

If Qt is installed but you get "Qt not found" errors during the build then make sure that you have added Qt's bin directory to your PATH environment variable. If you are compiling with the build.cmake script then please read the subsection Locating Qt.

Small icons in Qt Creator on Linux

If you have an HDPI display, you may find that Qt Creator's icons are too small or the interface is the wrong scale.

To fix this:

1. Open the Qt Creator launcher file for editing (here I use the nano editor):

   nano ~/.local/share/applications/org.qt-project.qtcreator.desktop

2. In that file, locate the line starting Exec. It will look something like this:

   Exec="/full/path/to/qtcreator" %F

3. Edit the Exec line and also add a TryExec as follows, using the same path as before:

   TryExec=/full/path/to/qtcreator
   Exec=env QT_AUTO_SCREEN_SCALE_FACTOR=1 "/full/path/to/qtcreator" %F

   Careful! You can use quotation marks (") on the Exec line but not the TryExec line.

4. Save the file (in nano, press Ctrl+O to "output", then Enter to confirm the file name).

5. Try launching Qt Creator. If it worked and the icons are the right size, you can close the launcher file (press Ctrl+X to exit in nano).