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.


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.

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

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)

Add new comment

(If you're a human, don't change the following field)
Your first name.
(If you're a human, don't change the following field)
Your first name.

Filtered HTML

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.