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

Add new comment