Get MuseScore's source code

Summary

1. Create your src folder
2. Fork MuseScore's repository
3. Clone the repository
   • Working directory
4. Set the remotes
5. Create multiple worktrees (optional)

You must have Git installed on your computer. See Set up Developer Environment.

Create your src folder

Create a folder called src to store source code projects on your machine.

Tips for creating the src folder

We recommend calling it src to keep the name as short as possible. This helps when using the terminal. Also, it's essential on Windows due to the MAX_PATH limit (see below). Avoid spaces, special characters, and non-ASCII characters in the names of all parent directories. These characters can cause problems during compilation or when running terminal commands. Ensure you have read and write permission for the src folder and all its contents. Never use sudo or "Run as administrator" to compile source code. Locate it on a drive that's internal to your machine. Using an external or network drive reduces Git performance and slows down compilation. Locate it on a modern filesystem that's native to your operating system. Native filesystems: NTFS on Windows, APFS on macOS, EXT4 or BTRFS on Linux. Using a non-native filesystem reduces Git performance and slows down compilation. Don't share it between multiple operating systems (Windows, macOS, Linux, etc). Sharing between multiple operating systems reduces Git performance and can lead to corruptions. However, sharing with multiple versions of the same OS (e.g. Windows 10 & 11, or Ubuntu & Fedora) should be OK as long as a similar version of Git is used on each one. Don't use a location that's backed-up or synced by other software (e.g. iCloud, OneDrive, Dropbox, Syncthing, etc). Instead, make commits regularly and push them to a remote repository (your fork) to create a backup.

Windows

Create your src folder at the root of an NTFS-formatted drive, such as your C: drive:

# Change to the C: drive's root directory:
cd C:\              # PowerShell or CMD
cd /c               # Git Bash

# Create a new directory for code projects:
mkdir src

It must go at the root of the drive to avoid encountering the 260 character MAX_PATH limit Windows places on the length of file paths. (Code projects like MuseScore often contain files with long names and many layers of subdirectories, particularly inside the build folder.)

Linux and macOS

Normally, it's best to create your src folder inside your Home directory:

cd ~                # Change to your Home directory.
pwd                 # Print its full path. (See below to check it's OK!)
mkdir src           # If the path is OK, create a new directory for code projects.

However, paths with unusual characters can cause problems when you try to compile or run terminal commands.

/home/Francois-Pierre42     ✔️ OK
/Users/Francois_Pierre42    ✔️ OK
/@home/Francois+Pierre      ❓ Contains special characters (@+) but probably still OK.
/home/Francois Pierre       ❌ BAD: Contains space.
/Users/FrançoisPierre       ❌ BAD: Contains non-ASCII character 'ç'.

If this affects you, move the src folder elsewhere and run sudo chown -R "${USER}" src to make yourself the owner. (Next time you set up a user account, try to use only ASCII letters, numbers, hyphen, and underscore in the Home path.)

Fork MuseScore's repository

A 'fork' is a remote (i.e. online) copy of a repository. It can be edited freely without affecting the original repository.

Tip

If you just want to compile the code, not edit it, then you can skip this and move straight to Clone the repository.

To create a fork:

1. Sign in to GitHub (create a free account if necessary).
2. Visit MuseScore's official repository page: https://github.com/musescore/MuseScore
3. Click the "Fork" button in the top right to create your personal fork.

Your fork exists at https://github.com/USERNAME/MuseScore where USERNAME is your GitHub username (e.g. shoogle's fork is here).

Clone the repository

A clone is a local (i.e. offline) copy of a repository. It's basically a folder on your computer that contains the source code for you to edit and/or compile.

If you made a fork then you should clone it here, otherwise clone the official repository. Make the clone inside your src folder.

# Change to your src folder. For example:
cd ~/src            # Linux and macOS
cd C:\src           # Windows - PowerShell or CMD
cd /c/src           # Windows - Git Bash

# Clone your fork if you have one:
git clone https://github.com/USERNAME/MuseScore  # Replace USERNAME with your GitHub username.

# Otherwise clone the official repo:
git clone https://github.com/musescore/MuseScore

Working directory

The git clone command put the code in a new folder called "MuseScore". You should change to it now:

cd MuseScore

Unless otherwise stated, this folder is used as the working directory for all subsequent commands, including on subsequent pages of this guide.

About the MuseScore folder

Inside this folder is a hidden directory called .git, which contains Git's history of commits, branches, and tags, as well as an index, or staging area, for changes that are about to be committed. Everything outside the .git folder is known as the working tree. The commands git status and git diff show the state of the working tree compared to the index, and git diff --cached shows the state of the index compared to the latest commit on your current branch. Technically speaking, edits to the working tree are not "in the repository" until you stage them (i.e. add them to the index: git add .) and create a commit (git commit). Even then, the changes are only in your local repository. To get them included in the offical repository, see Submit a Pull Request. ⚠️ Important: You shouldn't make any changes in the working tree until after you've successfully compiled and run the program.

Set the remotes

Git is able to push (upload commits to) and pull (download commits from) remote repositories, known as "remotes".

Run these commands to set the remotes for your local repository:

# If you cloned your fork earlier:
git remote add upstream https://github.com/musescore/MuseScore.git
git remote set-url upstream --push disabled  # Prevent accidental push to official repo (team members only).
git pull upstream master                     # Get latest commits from official repo.
git branch -u upstream/master                # Track the official master branch instead of your fork's master branch.

# Optional: Use SSH instead of HTTPS for pushes (Linux & macOS only):
git remote set-url origin --push git@github.com:USERNAME/MuseScore.git  # Replace USERNAME with your GitHub username.

# If you cloned the official repo:
git remote set-url origin --push disabled    # Prevent accidental push to official repo (team members only).

Explanation

When you cloned the repository, a default remote called origin was automatically created. It points to the URL you used with git clone, which was either your fork or the official repo. When origin is a fork, the convention is to create another remote called upstream that points to the official repo. This is useful later when you want to pull new commits from the official repo in order to keep your local repo up to date with other developers' changes. We pull from the official repo but we never push to it. (Instead, we push to our forks, create PRs, and merge them via the GitHub interface.) Therefore, push should be disabled on whichever remote represents the official repo. But if you're not a team member, you don't need to worry about this because GitHub won't allow you to push to the official repo anyway. Tracking the upstream master branch means that git status will show how many commits your local master branch is ahead or behind the upstream master branch. If you're on Linux or macOS, using SSH saves having to reenter your password every time you push local commits to your fork on GitHub. However, SSH requires additional setup, and it's often blocked by firewalls on public WiFi networks, so it's only worth it for tasks that require authentication. Pulling from a public repo doesn't require authentication, but pushing does, hence we only recommend using SSH for pushes. If you're on Windows, it's better to stick with HTTPS for pushes if you want your password to be remembered.

Use this command to view the names and URLs of all remote repositories that Git is aware of:

git remote -v

Tip

You can add more with git remote add [name] [url]. This can be useful to fetch code from another user's fork.

Create multiple worktrees (optional)

Tip

If you're new or you're only an occassional contributor, skip this section and go straight to Install dependencies. You can come back here and complete this section at any time.

Git worktree provides an efficient way to have multiple copies of the code on your machine. You should consider using this feature if any of the following are true:

• You have multiple PRs open at the same time.
• You're reviewing or rebasing someone else's PR.
• You're porting PRs (or cherry-picking commits) between branches.
• You need to inspect code on an older branch (e.g. 3.x).

By performing these actions on a secondary worktree, you can avoid modifying files on your main worktree, thereby avoiding the need to recompile lots of files unnecessarily.

Note

You could achieve this by cloning the repository multiple times, but the advantage of using worktrees is that they all share the same hidden .git folder (i.e. the same history of commits, branches, and tags). The files are still duplicated but the history isn't. This saves space on your machine and makes it easy for you to transfer code between worktrees simply by switching branches locally; no need to push anything to a temporary branch on a remote repository.

If you want to proceed, instead of storing the code directly in the 'MuseScore' folder, we'll now store it in subfolders:

# OLD STRUCTURE:
src/                # Your src folder.
└── MuseScore*      # LOCAL REPO: Used for everything!

# NEW STRUCTURE:
src/                # Your src folder.
└── MuseScore/      # Ordinary folder called 'MuseScore'.
    ├── master*     # LOCAL REPO: Main worktree for editing & compiling C++ and CMake files.
    ├── release?    # Worktree for porting PRs to the current release branch.
    ├── rebase      # Worktree for rebasing PRs. (Once rebased, check them out on the main worktree to compile.)
    ├── scripts     # Worktree for editing non-C++ and non-CMake files.
    └── old?        # Worktree for inspecting old branches (e.g. 3.x).

# KEY:
* # You would compile this worktree.
? # You might compile this worktree if the need arises.
  # Other worktrees would not be compiled.

You don't have to create all of these worktrees. At a minimum, all you need is master and one other worktree.

If you have yet to clone the repository, the steps would now be:

# Change to your src folder. For example:
cd ~/src            # Linux and macOS
cd C:\src           # Windows - PowerShell or CMD
cd /c/src           # Windows - Git Bash

# Clone your fork to 'MuseScore/master' instead of the usual 'MuseScore':
mkdir MuseScore
cd MuseScore
git clone https://github.com/USERNAME/MuseScore master  # Replace USERNAME with your GitHub username.
cd master

If you already cloned at the normal location, you can adjust your existing setup like this:

cd ..                            # Go outside the 'MuseScore' folder.
mv MuseScore master              # Rename the 'MuseScore' folder to 'master'.
mkdir MuseScore                  # Create an empty folder called 'MuseScore'.
mv master MuseScore              # Move the 'master' folder inside the 'MuseScore' folder.
cd MuseScore/master              # Change to the 'master' folder.

Either way, now you can go ahead and create the worktrees:

git switch master                # Default branch for worktrees that don't specify an alternative.

git worktree add ../release 4.7  # Create 'release' worktree based on '4.7' branch.
git worktree add ../rebase       # Create 'rebase' worktree based on default branch (master).
git worktree add ../scripts
git worktree add ../old 3.x

To demonstrate how you would use the worktrees, let's pretend:

• Your main worktree (master) points to the master branch, and you've successfully compiled it.
• You have a stale PR that's 2 commits ahead and 50 commits behind the master branch.
• You want to rebase the PR so it's 2 commits ahead and zero commits behind master.
• Optionally, you may also want to compile the PR and test it.

If you perform the rebase on the main worktree, you'll have to recompile 52 commit's worth of files. But if you perform the rebase on a different worktree, at worst you'll only have to recompile 2 commit's worth of files!

You would proceed as follows:

cd ../rebase                     # 1. Go to the 'rebase' worktree.
git switch your-pr-branch        # 2. Checkout the stale PR branch.
git rebase master                # 3. Rebase it on master.

# Done! Unless you want to compile the PR, in which case...

git switch rebase                # 4. Checkout any other branch (see NOTE below).
cd ../master                     # 5. Go back to the main worktree.
git switch your-pr-branch        # 6. Checkout the newly rebased PR branch.
                                 # 7. Recompile...

# NOTE: The same branch cannot be checked out on multiple worktrees simultaneously,
# hence the 'rebase' worktree must switch away from the PR branch in step 4 in order
# to make that branch available for the 'master' worktree to switch to in step 6.

By rebasing on a separate worktree, we avoided undoing and replaying 50 commits on the main worktree, so only the files touched by the 2 new commits have to be compiled, rather than files touched by all 52 commits.

In general, the goal of using worktrees is to reduce the need to switch branches on your compiled worktrees, and to minimize the number of files that are modified (and hence must be recompiled) when you do need to switch branches.

---

Previous	Current	Next
Install Qt and Qt Creator	Top of page	Install dependencies