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 might receive occasional marketing emails and newsletters, but you can unsubscribe via the link at the bottom of the emails.

Download the online installer

Visit https://www.qt.io/download-qt-installer and download the installer file. It doesn't matter where you save it. You won't need it again after the installation is complete.

Run the online installer

Windows

Double-click on the installer executable in File Explorer. You might even be able to 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

To run the installer via Terminal:

cd ~/Downloads             # Or wherever you saved the installer file.
chmod +x qt-unified-linux-*-online.run  # Grant execute permission.
./qt-unified-linux-*-online.run         # Execute (run) the installer.

# You may see an error message along the lines of:
"Error while loading shared libraries: libxcb-xinerama.so.0: cannot open shared object file: No such file or directory"

# If so, you need to install the missing library and then run the installer again.
sudo apt install libxcb-xinerama0

To run the installer via your file manager:

1. Right-click on the installer file and choose Properties.
2. Look for Permissions and Allow file to run as a program (or similar).
3. Enable that option then close the Properties dialog.
4. Double-click on the installer file to run it.
   • If nothing happens, try running it from Terminal instead.

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 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 (write this down or save it in a password manager like Bitwarden)

You'll have to check your inbox for a verification email and fill in some extra details on the Qt website. (They ask for your phone number but you don't have to give it.)

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

Pick the directory where Qt will be installed (best use the default one unless you have a good reason not to).

Make sure you select custom installation (don't use a default option).

We don't use Qt Design Studio, so you don't need that or anything else Qt offers you on this screen.

You probably don't want to associate common file types with Qt Creator. Normally you will open files from within Qt Creator, which doesn't require association. If you're opening files directly from your file manager then you're not getting the benefits of the IDE, so you might as well use an ordinary text editor (it'll be faster too).

Select Qt components

Different versions of MuseScore Studio require different versions of Qt

MuseScore Studio	Linux	macOS	Windows
4.3.x and earlier	5.15.2	5.15.2	5.15.2
4.4.0 - 4.4.2	6.2.4	6.2.4	6.2.4
4.4.3	6.2.4	6.2.4	6.2.9, but 6.2.4 is fine too
4.5	6.2.4, soon 6.8	6.2.4, soon 6.8	6.2.4, soon 6.8

Note: Qt 6.2.9 is not available prebuilt from Qt directly, only the sources. If you don't want to build it from the source, you can get it from the same place GitHub CI gets it from, a repository of @Casper Jeukendrup

1. At the right hand side, under Categories, select Archive and click Filter.

2. Next to Categories, click Information. The box below will display details about things you select in subsequent steps.

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

4. Expand (don't select) the desired Qt version chosen from the table above

   • In case you don't see these versions, click the "Archive" checkbox in the panel at the right, and click "Filter".

5. From this version, select only these things:

   • In the case of Qt 6:
     1. The main prebuilt component for your compiler (see Choosing the prebuilt component below).
        • Make a note of the one you used so that you can install the matching compiler later on.
     2. Qt 5 Compatibility Module
     3. From Additional Libraries:
        1. Qt Network Authorization
        2. Qt State Machines
   • In the case of Qt 5:
     1. The main prebuilt component for your compiler (see Choosing the prebuilt component below).
        • Make a note of the one you used so that you can install the matching compiler later on.
     2. Qt Network Authorization (or Qt WebEngine if you want to compile MuseScore 3).

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

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

   1. Qt Creator (cannot be deselected)
   2. CMake
   3. Ninja
   4. Windows only: Depending on the prebuilt component chosen in 4i:
      • MSVC only: Qt Creator CDB Debugger Support and Debugging tools for Windows.
      • MinGW only: MinGW itself (version must match that chosen in 4i).

Choosing the prebuilt component

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

Platform	Recommended compiler	Name of prebuilt component in the tree view
Linux	GNU Compiler Collection (gcc)	Desktop gcc 64-bit
macOS	Clang	macOS
Windows	Microsoft Visual C++ (MSVC)	MSVC 2019 64-bit

Other compilers (e.g. MinGW, WebAssembly) are not recommended for compiling MuseScore. They may work but we don't have CI builds for them, so compilation is liable to break from time to time. If it does break and you manage to fix it, feel free to send us your fix in a pull request.

MinGW is known to not build 4.0 and later anymore, due to the new WASAPI sound system, even with MUE_BUILD_CRASHPAD_CLIENT, MUE_BUILD_MUSESAMPLES_MODULE set to OFF (those don't build with MinGW either), see comment.

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 manager can be quick and easy. However, the Qt provided by your package manager might be:

• The wrong version of Qt (see the table above).
• 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

TODO: Add information about Qt 6 (the info below is only about installing Qt 5)

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 we 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).