Upgrading Moodle to a newer branch using git

In this post, I describe how to upgrade a Moodle installation from one major version to a newer one using the command line and git.

When it comes to open-source e-learning platforms, Moodle is pretty much the only game in town. With masses of features and numerous contributed plugins, it's very powerful and customisable. On the downside, it has a very heavy performance footprint, and upgrading it can be rather an involved process. There aren't any helpful Debian packages and the documentation is a bit patchy in places. Using git to keep Moodle up to date takes a lot of the pain away, but it's still difficult to find clear step-by-step instructions. The following guide collects together a few bits of information I've collected about git and Moodle from various places on the internet.

  1. Back up your Moodle installation:
    1. cp -a /path/to/moodle /path/to/moodle.bak
    2. mysqldump -u [moodle_database_user] -p [moodle_database_name] > moodle_database_backup.sql
  2. Enable maintenance mode and switch to the newer branch — you can skip the branch checkout if you're only upgrading between minor versions. Replace XY with the correct version number, e.g. 26 for Moodle 2.6.x:
    1. cd /path/to/moodle
    2. $(which php) admin/cli/maintenance.php --enable
    3. git remote update
    4. git checkout -b MOODLE_XY_STABLE origin/MOODLE_XY_STABLE
    5. git pull
  3. Upgrade the database and disable maintenance mode:
    1. $(which php) admin/cli/upgrade.php
    2. $(which php) admin/cli/maintenance.php --disable
  4. Login to the site and check the version number is correct on Site administration → Notifications
  5. Upgrade any contributed plugins by visiting Site administration → Plugins → Plugins overview and clicking “Check for available updates”.
  6. (Optional) Remove the old branch with git branch -d MOODLE_AB_STABLE where AB is equivalent to the old version number, e.g. 25 for Moodle 2.5.x.


Lewis Carr - Fri, 07/08/2015 - 13:52


Hi Alex, I am a long term Moodle user and was trying to pull a tutorial together for a friend of mine. Anyway, rather than write from scratch I did a Google search, found your article. Tested it. Works like a charm. Thank you

Hi Alex,
Very helpful, thanks a lot.
That gave me all the needed information to successfully upgrade a simple installation.

Hi Alex,

Thanks for taking the time to share this! This was a nice reminder for me now that the 3.1 LTS version is available, and it worked perfectly for me.

Not sure why everyone is thanking someone called Alex since it was me who wrote this article, but I’m glad it’s proving useful!

Hi John, it's for nesting bash commands. Type $(command) and it will attempt to run command and then run its output. For example, on my laptop, which php returns /usr/bin/php, so $(which php) is equivalent to running /usr/bin/php. For simple commands that are in your users $PATH it's probably unnecessary, but it can be handy for more complex commands.

After I run this command : $(which php) admin/cli/upgrade.php
I got this message: No upgrade needed for the installed version 3.3+ (Build: 20170525)
(2017051500.02). Thanks for coming anyway!

I also try to update using git command:
sudo git pull, but the notification still show old version. Please help. Thanks

Bernhard - Fri, 28/07/2017 - 21:00


Originally I had cloned with

> git clone --depth=1 --single-branch -b MOODLE_28_STABLE git://git.moodle.org/moodle.git moodle_code

Therefore the new branch was not available. I had to

> git remote set-branches --add origin MOODLE_31_STABLE
> git fetch --depth=1
> git checkout -b MOODLE_31_STABLE --track origin/MOODLE_31_STABLE

Why should I pull after the git checkout? Of course I need to pull when I want to update within the branch (MOODLE_31_STABLE)

Michael Milette - Mon, 12/07/2021 - 21:51


Hi Pete,

Good article. While your process certainly works, it could use a few tweaks to ensure that you can rollback if needed.

1. You should start by putting your site into CLI maintenance mode (not maintenance mode from inside Moodle) before you start your site backup. This disables any updates to the database and moodledata files thereby preserving the integrity of both of these. Otherwise the cron job or admin user activity in Moodle could cause these to fall out of sync with each other.

instructions for CLI maintenance mode can be found at:

2. You should also backup your moodledata files.

Hope you find this information useful.

Thanks again for sharing this information with the Moodle community. The world could use more people sharing.

Best regards,

Michael Milette

Hi. I am new to Moodle platform. I just want to upgrade 3.11 to 3.12 on my Windows PC but I don't know how. The commands you posted above is really confusing where to execute those. Please help me.. Can you do a video step by step process on upgrading Moodle?

Hi Roy, I'm afraid that this guide is specifically related to upgrading Moodle if you installed it using a program called git. From the information you've provided, it sounds very unlikely that you used git to install Moodle, so the instructions above won't be any help I'm afraid. I can only recommend that you refer back to the original guide you used when setting it up in the first place. Apologies not to be more help.

Can you elaborate? Upgrading with git within the same version number used to be pretty straightforward and well covered elsewhere, which is why it wasn’t included in this article. It’s been a while since I worked with Moodle so perhaps the upgrade process has become more complex. I wrote this article because I kept running into issues trying to upgrade between versions and wanted to capture the steps to solve that specific problem, rather than as a general guide to Moodle upgrades.

Add new comment