Install Qt and Qt Creator

Summary

• Installing via the online installer (recommended)
• Installing via a package manager (not recommended)
• Fixing the "Qt not found" CMake error
• Workaround for Qt Creator scaling issue on Linux

Installing 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.

Custom installation

Use the default installation folder (unless you have a reason not to), but make sure you do a 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 Qt 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 (more details 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)

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 the Maintenance Tool program located in the Qt installation folder. The default location is:

Linux: ~/Qt/MaintenanceTool

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

Installing via a package manager (not recommended)

Using a package manager may seem quicker and easier than using the online installer, but most package managers don't allow you to pick the version of the things you install, so it's pot-luck whether it gives you the right one.

Debian-based systems

If your repository has Qt 5.15 or later, install Qt by (as root):

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 (as root):

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.

Fixing the "Qt not found" CMake error

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.

Workaround for Qt Creator scaling issue on Linux

If you use the Qt Creator IDE on an HDPI display, you may notice that icons are very small or the interface is the incorrect scale. To fix this,open the file ~/.local/share/applications/org.qt-project.qtcreator.desktop in a text editor and look for the line starting Exec. It will look something like this:

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

Edit that line and also add a TryExec as follows, keeping the path the same 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.

Save the .desktop file and try opening Qt Creator again.