Skip to content

Install Qt and Qt Creator

Jump to bottom Edit New page
Peter Jonas edited this page Sep 10, 2023 · 19 revisions

Summary

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 the emails.

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 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 these things:

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

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

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

Add a custom footer

Testing

Translation

Compilation

  1. Set up developer environment
  2. Install Qt and Qt Creator
  3. Get MuseScore's source code
  4. Install dependencies
  5. Compile on the command line
  6. Compile in Qt Creator

Beyond compiling

  1. Find your way around the code
  2. Submit a Pull Request
  3. Fix the CI checks

Misc. development

Architecture general

Audio

Engraving

Extensions

Google Summer of Code

References

Clone this wiki locally