Upgrading

Moodle is designed to upgrade itself from one version to the next. The procedure is

Back up everything.
Replace the old version of the code with the new one.
Visit the administrator notifications link, which triggers Moodle to self-update.

These steps are explained in more detail below.

Sometimes there are specific considerations when upgrading to a particular version. Please refer to Upgrading to Moodle 1.6, Upgrading to Moodle 1.8, Upgrading to Moodle 1.9 or Upgrading to Moodle 2.0 if applicable. You also have to be more careful if you have installed additional plug-ins or customised the code.

See this tutorial if you are upgrading Moodle on cpanel. It is a bit rough around the edges and is a little dated, but you should get the idea.

There is also a separate page about upgrading Moodle if you installed it using the Ubuntu/Kubuntu/Debian package manager.

When upgrading a Moodle installation you should follow these steps:

Before you upgrade your site for real

You are strongly advised to make a copy of your entire Moodle site onto another computer (see Moodle migration) and run the upgrade there to verify it will work.

Check the requirements

Spend some time re-reading the installation documentation and documentation for the new version. Check the system requirements for the target version you want to upgrade-to in Administration > Server > Environment.

Put your Site into Maintenance Mode

Before you begin upgrading your site, you should put it into Maintenance Mode to stop any non-admin users from logging in.

Backup important data

See Site backup for more specific information.

There are three areas that should be backed up before any upgrade:

Moodle software (For example, everything in server/htdocs/moodle)
Moodle uploaded files (For example, server/moodledata)
Moodle database (For example, the SQL or Postgres database)

Experienced site administrators know that it is a best practice (a very good idea) to make a backup of any production system before a major upgrade. In fact, it is a good idea to automate your server to backup your Moodle installation daily. Most upgrades on sites that have used the standard Moodle packages (no contributed code and no little tweaks to the php files), will not have any major issues with the upgrade process.

TIP: One more time, "do not risk what you can not afford to lose": do regular backups, make sure it is really backed up and know how to restore a backup!

Install the new Moodle software

Upgrading can be a simple process or a more complicated process. Sites that have not used contributed code and are migrating from say Moodle 1.x.1 to 1.x.3 should not have a problem. However, we still recommend that with any production server that you have made a successful backup of the MySQL database, the moodledata directory and the moodle program folders and files.

Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new installations. Review the backup section above.

Standard install package

Having read the cautions about backups, download a copy of the standard install package. Here is a set of simple instructions for an average site.

It is probably a good idea to use the Site administration block>Server>Maintenance mode to prevent user activity as the site upgrades.
Having moved your old Moodle software program files to another location, unzip or unpack the upgrade file so that all new the Moodle software program files are in the location the old files used to be in on the server. Moodle will adjust SQL and moodledata if it needs to in the upgrade.
Copy your old config.php file back to the new Moodle directory.
If you had added any custom plugins or themes into your Moodle you can add them to the new code. It is important to check that you get the correct version for your new version of Moodle. You should check in the optional plugins database. Be particularly careful that you do not overwrite any code in the new version of Moodle. If you are upgrading to Moodle 2.0 or newer, note that all optional plugins and themes required a significant rewrite and most do not have 2.0 versions (yet).
Use the notification link in the site administration to start the upgrade process. You will see a series of lines or screens indicating progress.
After a successful upgrade, turn off the maintenance mode, so your users can get into the site.

Using a downloaded archive

In some installs, the site administrator may overwrite the Moodle code with a backup copy. Or create a new clean install copy of Moodle, then restore an archive (via a compressed file or parts of a saved set of Moodle code files and folders).

Do not overwrite an old installation unless you know what you are doing ... sometimes old files can cause problems in new or "cleaned" installations. The best way is to rename the current Moodle code directory (for example rename "moodle" to "moodleold"), then unpack the new Moodle archive into the old location (for example, a new directory called "moodle").

Linux

mv moodle moodle.backup
tar xvzf moodle-1.1.tgz

Next, copy across your config.php, any other plugins such as custom themes, and your .htaccess file if you created one (check that optional/custom plugins are the correct version for your new Moodle first):

cp moodle.backup/config.php moodle
cp -pr moodle.backup/theme/mytheme moodle/theme/mytheme
cp -pr moodle.backup/mod/mymod moodle/mod/mymod

Don't forget to

sudo chown www-data moodle/config.php

if necessary.

where www-data is whatever user the Apache user is on your system. This is often 'apache' or 'www'. You can find out by doing 'ls -l' in your /var/www/moodle folder (or wherever your moodle site is) and then looking at the owner and group.

so you may see something like

ls -l
...lots of lines...
-rw-r--r--   1 apache system     784 Jun 28  2007 config.php 
...lots more lines...

so the owner is apache and the group is system.

To replicate this on your new system you can do 'chown apache:system config.php'

or to do a whole group do

chown apache:system ./*

and recursively

chown -R apache:system ./*

Using CVS

You can use CVS for updating or upgrading your Moodle. First you need to do a CVS checkout in your (empty) Moodle root directory.

You can use any of our CVS Mirror servers. Just replace SERVER.cvs.moodle.org in the instructions below with the name of the mirror server you chose!.

For Linux servers

To do a CVS checkout of Moodle, you first have to logon to the Moodle CVS server.

 cvs -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle login
 No password for anonymous, so just hit the Enter button.

Go to the directory where you want the Moodle root to come and type

 cvs -z3 -d:pserver:anonymous@SERVER.cvs.moodle.org:/cvsroot/moodle co -r MOODLE_18_STABLE moodle 
 (where MOODLE_18_STABLE is the desired version)

To update, just go into the Moodle root directory and update to the new files:

 cvs update -dP

To update to a new version type in the following and change 18 to whatever newest version upgrade number is

 cvs -Q update -dP -r MOODLE_18_STABLE

Make sure you use the "d" parameter to create new directories if necessary, and the "P" parameter to prune empty directories.

For Windows servers

You can use Tortoise CVS to do the initial checkout and the updates.

If you have been editing Moodle files, watch the messages very closely for possible conflicts. All your customised themes and non-standard plugins will be untouched.

Do not forget to trigger the install process in the site administration block (see below).

Using Git

You can use Git for updating or upgrading your Moodle. First you need to do a Git checkout in your (empty) Moodle root directory.

See Git for Administrators for further details.

Finishing the upgrade

The last step is to trigger the upgrade processes within Moodle.

To do this just visit the Site administration block admin page (or http://example.com/moodle/admin) and the "Notifications" link.

Moodle will automatically detect the new version and perform all the SQL database or file system upgrades that are necessary. If there is anything it can't do itself (very rare) then you will see messages telling you what you need to do.

Assuming all goes well (no error messages) then you can start using your new version of Moodle and enjoy the new features!

TIP: Use the site administration block>Server>Maintenance mode to prevent users from changing data during the upgrade.

TIP: If you are running a large scale Moodle site (e.g. have more tha 10,000+ courses and 40,000+ users), make sure that you do your own performance profiling testing. Post a thread or check the Installation problems forum and check Tracker for potential issues.

Verify the upgrade (optional)

If you wish to confirm that the database definitions in the upgraded database match the definitions of a new, clean install (which they should) you might like to look at Verify Database Schema.

Upgrading more than one version

In general, it is recommended to upgrade via the newest of each major version of Moodle, for example 1.7 -> 1.9. An exception to this is when upgrading from 1.5 or 1.6, when it is recommended that 1.7 and 1.8 are skipped, in other words upgrade 1.5 -> 1.6 -> 1.9. (The main reason for this recommendation is that the default roles settings obtained when upgrading to 1.7 are not ideal for 1.8 onwards, 1.8 has problems with groups, etc.)

Documentation