Compile instructions (macOS) - Git

Updated 1 year ago
This page shows old instructions for MuseScore 1.
For MuseScore 4 users, see Compile instructions (macOS) - Git.

    Use these instructions to compile MuseScore master branch with Xcode and Qt 5.12 on macOS 10.12+. See the Versions Reference page for which macOS versions are supported by Qt 5.12.
    As of 484f8dc, 09Oct2020, Qt 5.15 (and a C++17 capable toolchain) is required for the master branch. This excludes macOS 10.12 (and lower). The 3.x branch will stay in Qt 5.9 though.

    Setting the build and development environment

    1. Install the latest version of Xcode from the Mac App Store.

    2. Launch Xcode and accept the licence.

    3. In Xcode, go to Preferences -> Download and install the Command line Tools. With Xcode 5, you might need to run xcode-select --install instead.

    4. Install the dependencies. If you are new to macOS development or do not have a preference, we suggest Homebrew,

          $ ruby -e "$(curl -fsSL"
          $ brew install libogg libsndfile libvorbis pkg-config portaudio jack lame cmake git uncrustify

    If you prefer MacPorts, choose the DMG of your OS and install MacPorts.
    Open a terminal and enter the following (in your home):
    $ sudo port install git libsndfile pkgconfig lame portaudio jack cmake qt513

    1. Install Qt. It's possible to do this via Homebrew or MacPorts, but the recommened way is to use the Qt Online Installer (open source version, not commercial), which is available from the link at the bottom of this page. Open the DMG and double-click the installer (no need to drag to your Applications folder). You'll have to sign-in / create a Qt account and agree to terms (probably as "an individual not working for any company" unless a company is paying you to work on MuseScore). When asked, do a Custom Installation. Under Qt 5.15.2 (i.e. the latest non-Qt 6 version), make sure the components labelled macOS and Qt WebEngine are selected. Also, at the bottom of the window, under Developer and Designer Tools, make sure that CMake and Ninja are selected.

    2. Add Qt's binary folder to your PATH environment variable. To do this, open the hidden text file ~/.bash_profile (if that file exists), or alternatively use ~/.profile. If neither file exists then create ~/.profile. Append the following line to the file you just opened:

        export PATH="${PATH}:${HOME}/Qt/<QT_VERSION>/clang_64/bin"

    Make sure you substitute <QT_VERSION> for the actual version you installed. E.g. for Qt 5.15.2:

        export PATH="${PATH}:${HOME}/Qt/5.15.2/clang_64/bin"

    You must update the version number in this file every time you update Qt itself via the MaintainanceTool.

    1. Clone the repository from GitHub into your home directory:
          $ cd ~
          $ git clone git://

    If you plan to contribute to MuseScore, you can setup your own fork on GitHub and clone it instead. See the Git Workflow page.

    Building MuseScore

    1. In a terminal, enter:
      $ cd MuseScore
    2. Set the revision SHA1 for this build
      $ make -f Makefile.osx revision
    3. Start the actual compilation. It takes more than one hour on a MacBook 2 GHz but it's pretty fast on a MacBook Pro Core i7 (4 to 5 minutes max).
      $ make -f Makefile.osx release
    4. Call the install target. The bundle is copied from the Release directory into the applebuild directory. All resources (such as help and templates) are added to it
      $ make -f Makefile.osx install
    5. The package step. This target calls a script derived from this one. It creates a self-contained bundle, thanks to macdeployqt, by adding and stripping the Qt libraries into the MuseScore bundle. It also adds Qt plugins, PortAudio and libsndfile. A DMG file is the result
      $ make -f Makefile.osx package

    Debugging and developing MuseScore

    If you are a developer, look at the xcode target in the makefile. It generates a xcodeproj file. You can open this xcodeproj file and use the Apple IDE for tasks such as modifying, debugging and compiling MuseScore code.

    $ make -f Makefile.osx xcode

    Then open the xcodeproj bundle in Xcode
    $ open build.xcode/mscore.xcodeproj

    In Xcode, run the ALL_BUILD scheme. It will compile all the files. Then run the install scheme. It will install the required files (fonts, images etc...) for runtime. Debug by running the mscore scheme.

    If MuseScore won't start

    You may get this error message on the Xcode Console when you try to run the mscore scheme:

    This application failed to start because it could not find or load the Qt platform plugin "cocoa".

    This mean MuseScore can't find the Qt plugins. You need to edit the mscore scheme to set the environment variable QT_PLUGIN_PATH to point to your Qt plugins directory. The default value for Qt 5.12 is:


    The actual value you need to set depends on your Qt version (which you can find with qmake -v) and where you installed it earlier on. You may also need to expand the tilde (~) to it's full value /Users/<username> to point to your home directory.

    If MuseScore doesn't start for any other reason then try reverting to factory settings, but make sure you revert the compiled mscore debug build rather than the official version if you have it installed.

    Debugging in Xcode 5+

    In Xcode 5+, you might need to uncheck “Allow debugging when using document Versions Browser” in Product-->Edit Scheme .. -->Run Otherwise --NSDocumentRevisionsDebugMode YES gets passed to MuseScore, and it doesn't know how to handle it.

    In Xcode > 5, you'll find the menu item elsewhere. Product-->Scheme->Edit Scheme..
    Select Run (on the left hand side), and select Options along the top of the form.
    Then you'll find "Allow debugging when using document Versions Browser" in the form. Uncheck the checkbox.


    The preferred way to contribute is via a Pull Request on GitHub. Patches are also welcome on the Developer Mailing List, or on the Issue Tracker.

    Building a release for distribution

    # may no longer be relevant as this is for 10.7. Please review and remove this comment or the paragraph
    Dependencies built with Homebrew will not run on older versions of macOS. Here is a zip file with the dependencies as "bottles" built on Mac OS X 10.7. They can be installed with
    brew install {file}.tar.¹