This page explains in detail how to upgrade Moodle. For a summary of the process, see Upgrade overview.
| Warning:
The directory structure of Moodle files and the security model have changed in 5.1. 1. A new "public" folder has been introduced to contain all web accessible files. Configuration and other sensitive files are now stored outside this folder for better security. 2. You will need to reconfigure your web server to accommodate the security change as part of the upgrade process. See the section below Code directories restructure. |
Check the requirements
Before upgrading, check that your server meets all requirements for 5.1 in Site administration > Server > Environment.
See the Moodle 5.1 release notes for server and client software requirements.
Note: You can only upgrade to Moodle 5.1 from Moodle 4.2.3 or later. If upgrading from earlier versions, you must upgrade to 4.2.3 or later as an intermediate step.
Before upgrading
We advise that you test the upgrade first on a COPY of your production site, to make sure it works as you expect. See Moodle_migration.
Consider setting the upgrade key for your site. The feature has been available for a while. It is now encouraged for better security.
Backup important data
There are three areas that should be backed up before any upgrade:
- Moodle software (For example, everything in server/www/moodle)
- Moodle uploaded files (For example, server/moodledata)
- Moodle database (For example, your Postgres or MySQL database dump)
See Site backup for more specific information.
Check for plugin updates
If you have Automatic updates deployment enabled, you can update installed plugins automatically during the upgrade. Just make sure you check for available updates (via the button for it) at the Site Administration > Plugins overview tool.
If you are updating plugins manually, now is a good time to check the Moodle Plugins directory to see if a 5.1 version is available for any plugins (including themes) installed on your site. If so, download the plugin package to prepare to copy it to the appropriate location in your Moodle code (see Installing plugins).
The plugin upgrade will then be part of the Moodle upgrade process.
If an outdated plugin causes your upgrade to fail, you can usually delete the plugin code instead of uninstalling it from within Moodle so that the data associated with it remains intact.
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. Then you should wait for any currently running cron processes to complete before proceeding.
Code directories restructure
The directory structure of Moodle files and the security model have changed from 5.1.
In previous versions, the entire Moodle codebase sat within the web server’s document root. From Moodle 5.1 onwards the /public folder is intended to be the only directory publicly accessible.
Important: You need to update your web server configuration so that the document root points to /moodle/public.
You can no longer simply place the Moodle files into your web root, instead you should aim to either:
- update the document root in your web server configuration to point to Moodle's
/publicdirectory; or - use a symlink to the Moodle
/publicdirectory; or - use a location-specific alias.
How this is configured will depend on your hosting provider.
Be sure to copy your old Moodle directory before making any changes.
Moodle in your Document Root
If your Moodle site is located in the root of your website rather than a subfolder then you may be able to use the following approach. This approach covers sites with URLs such as:
These instructions assume:
- that your username is
moodleuser - that your home directory is in
/home/moodleuser - that your directory root is in
/home/moodleuser/public_html
If you have shell access to the server
mkdir -p ~/sites/
mv ~/public_html ~/sites/moodle
ln -s ~/sites/moodle/public ~/public_html
If you previously had other non-Moodle content in your Moodle root then you should ideally move this into its own location and symlink it too, for example:
mkdir -p ~/sites/
mv ~/moodle/wordpress ~/sites/wordpress
ln -s ~/sites/wordpress ~/public_html/wordpress
In your browser, type "www.example.com/wordpress"
Using a PHP file executed from the web
In many cases, even if you do not have access to the shell, you are able to move files and create symlinks within your user account.
You may, for example, create a new updatelocation.php file in your document root with content:
<?php
$publichtml = __DIR__;
$parentdir = dirname($publichtml);
$sitesdir = "{$parentdir}/sites";
$newname = "{$sitesdir}/moodle";
$target = "{$newname}/public";
if (!dir_exists($sitesdir)) {
mkdir($sitesdir);
}
rename($publichtml, $newname);
echo "Renamed {$publichtml} to {$newname}\n<br>";
symlink($target, $publichtml);
echo "Creating new symlink to link {$target} to {$publichtml}\n<br>";
If you previously had other non-Moodle content in your Moodle root then you should ideally move this into its own location and symlink it too, for example after running the above script you could run:
<?php
rename("sites/moodle/wordpress", "sites/wordpress");
symlink("sites/wordpress", "public_html/wordpress");
Moodle in a subfolder
If your Moodle site is located in a subfolder of your website rather than in the domain root then you may be able to use the following approach. This approach covers sites with URLs such as:
These instructions assume:
- that your username is
moodleuser - that your home directory is in
/home/moodleuser - that your directory root is in
/home/moodleuser/public_html - that your Moodle installation is currently location in
/home/moodleuser/public_html/moodle
If you have shell access to the server
mkdir -p ~/sites/
mv ~/public_html/moodle ~/sites/moodle
ln -s ~/sites/moodle/public ~/public_html/moodle
Using a PHP file executed from the web
In many cases, even if you do not have access to the shell, you are able to move files and create symlinks within your user account.
You may, for example, create a new updatelocation.php file in your document root with content:
<?php
$moodledir = __DIR__ . '/moodle';
$parentdir = dirname(__DIR__);
$sitesdir = "{$parentdir}/sites";
$newname = "{$sitesdir}/moodle";
$target = "{$newname}/public";
if (!dir_exists($sitesdir)) {
mkdir($sitesdir);
}
rename($moodledir, $newname);
echo "Renamed {$moodledir} to {$newname}\n<br>";
symlink($target, $moodledir);
echo "Creating new symlink to link {$target} to {$moodledir}\n<br>";
Moodle as a subdomain
Many shared hosting platforms will allow you to modify the Document Root for subdomains, but not the main domain, that is they will not let you modify:
But they will let you modify:
To do this in cPanel you can navitage to the "Domains" tool to change the Document Root.
- Your Main Domain may not allow you to change the Document Root so click the button "Create a new Domain"
- The name of your new sub-domain can be moodle.(your domain name) (eg moodle.mymoodle.com
- Don't share the document root but add moodle/public to the directory where you want the files for this domain to exist.
- Look on your File Manager and you will see moodle.(your domain name) appears under home. It will have a moodle directory containing only an empty public folder.
- Delete the newly created moodle and public sub-directory, upload and unpack the moodle code to replace them. There now should be a moodle folder with files and a public subdirectory in your subdomain.
- Copy your old config.php file to the moodle directory in your subdomain.
- Your new moodle will be at moodle.mydomain.com.
For those with root level access to your server
If the root of your Moodle site is located at /var/www/moodle:
In Apache:
DocumentRoot /var/www/moodle/public <Directory /var/www/moodle/public> AllowOverride None Require all granted </Directory>
In Nginx:
root /var/www/moodle/public;
Configuration files will normally be found in /etc/apache2/sites-available/ directory for apache and /etc/nginx/sites-available/ for nginx. This would be a good time to also configure your router if you haven't already done so.
Apply the change then restart the web server.
Routing
A Router has been included with Moodle since Moodle 4.5 and its use will increase in coming release.
Apache
If you have access to the Apache configuration you can use the FallbackResource directive as follows:
<Directory "/path/to/your/site">
FallbackResource /r.php
</Directory>
If you do not have access to the Apache configuration, but your configuration allows setting the FallbackResource in an Override file, then you can create a .htaccess file in your Moodle public folder with the following content:
FallbackResource /r.php
If your host prevents the use of the FallbackResource directive, you may still be able to use mod_rewrite. See the documentation below for OpenLiteSpeed.
For more information on the FallbackResource directive see the Apache Documentation.
nginx
The nginx server does not support per-directory configuration. All configuration must be specified in the central configuration.
The configuration you require will depend on your overall nginx configuration and how php-fpm is integrated.
try_files $uri $uri/ /r.php$is_args$args;
OpenLiteSpeed (cPanel)
This configuration is also compatible with Apache.
The following should be placed into the .htaccess file of your Moodle /public directory.
RewriteEngine On
# If we have a request which:
# - is not a file;
# - but is a directory;
# - and the directory contains an index.php;
# then redirect to the index.php in that directory.
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} -d
RewriteCond %{REQUEST_FILENAME}/index.php -f
RewriteRule ^(.*)$ $1/index.php [L]
# Rewrite / to /index.php
RewriteRule ^$ ./index.php [L]
# Anything else should be redirected to the Moodle Router.
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ r.php [L,QSA]
Install the new Moodle software
You can download the latest release from Moodle downloads.
Standard install package
- Move your old Moodle software program files to another location. Do NOT copy new files over the old files.
- Unzip or unpack the upgrade file so that all the new 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 (not the public subdirectory).
As mentioned above, if you had installed any plugins on your site you should add them to the new code tree (Moodle directory structure) now. It is important to check that you get the correct version for your new version of Moodle. Be particularly careful that you do not overwrite any code in the new version of Moodle and that you place the plugin folders in the correct directory (the same directory that they are in in the current installation.)
Your moodledata folder should be located separately to your Moodle code folder and, as such, should not need anything done to it. Moodle 3.0 will throw a warning if it is located in a web accessible folder and the moodledata should never be located in the Moodle code folder. If you are moving your installation to a new server or new location on your server, then you will need to follow the Migration documents.
Linux
mv moodle moodle.backup tar xvzf moodle-latest-5.1.tgz
Next, copy across your config.php, any custom plugins, and your .htaccess file if you created one (check that custom plugins are the correct version for your new Moodle first):
cp moodle.backup/config.php moodle cp -pr moodle.backup/theme/mytheme moodle/public/theme/mytheme cp -pr moodle.backup/mod/mymod moodle/public/mod/mymod
Don't forget to make moodle/config.php (and the rest of the source code) readable by your www server. For maximum security the files should not be writeable by your server. This is especially important on a 'production' server open to the public internet.
chown -R root:root moodle (Linux debian - or even create a user especially for moodle. Don't use the web server user, e.g. www-data) chmod -R 755 moodle
If you use cron, take care that cron.php is executeable and uses the correct php command:
chmod 740 admin/cli/cron.php (some configurations need chmod 750 or chmod 755) copy the first line from cron.php (if it looks like '#!/usr/local/bin/php' or '#!/usr/local/bin/php5.3', no need to copy '<?php')
if necessary. However, for a simple upgrade, there should be no need to change anything with cron.
Using Git
You can use Git for updating or upgrading your Moodle. See Git for Administrators for details.
Important
Any third party plugins that you have installed will still be located in their original locations above the new /public folder. These will need to be relocated into their relative path within the new /public folder structure to have them continue to work.
Command line upgrade
On Linux servers, Moodle 5.1 supports running the upgrade from the command line, rather than through a web browser. This is likely to be more reliable, particularly for large sites.
Finishing the upgrade
The last step is to trigger the upgrade processes within Moodle.
If you put your site into Maintenance mode earlier; take it out now!
To do this just go to Site administration > Notifications.
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!
Note: If you are running multiple servers or find some functionality missing (such as the filepicker not loading) then you should purge all caches manually (via Site administration > Development > Purge all caches) after completing the upgrade.
Fatal error: Maximum execution time of 30 seconds exceeded...
If your server uses a main language other than English, you may encounter a 'Fatal error: Maximum execution time of 30 seconds exceeded' when you try to upgrade it. You can increase max_execution_time = 160 on php.ini to allow the scripts enough time to process the language update. Otherwise, you can switch to English as the default language before doing the upgrade and back to your original language after a successful upgrade. See the forum discussion at https://moodle.org/mod/forum/discuss.php?d=119598.
Possible issues that may affect you in Moodle 5.1
Activity chooser enhancements
Activity chooser items are organised into categories according to their purpose.
The setting 'Activity chooser tabs' in the Site administration is removed, as activities are no longer classified as activity or resource.
In the Activity chooser, to select an activity, you need to click it and then click the Add button. Alternatively, to quickly go to the Add activity page you can double-click an activity. Previously, a single click took you to the Add activity page; the Add button provides an improved user experience.
Section links block removed
The Section links block is no longer included in Moodle 5.1 onwards, as the course index includes links to sections.
The Main menu block is renamed Additional activities block. The block can also be used in courses in Single activity format to show links to additional activities in the course. The title of the block can be changed if required.
Social course format is disabled by default
Social course format is disabled by default in Site administration > Plugins > Manage course formats in Moodle 5.1 onwards, and will be removed in a future version, as the functionality is provided by Single activity format with Forum as the type of activity.
Any courses using Social format will remain unchanged, though it is recommended that you change the course format to Single activity format with Forum as the type of activity.
Forgotten password page reCAPTCHA
You can protect against automated attacks by adding reCAPTCHA to the forgotten password page in Site administration > Plugins > Manage authentication.
Media drag and drop setting removed
Media drag and drop is always enabled. The setting 'Media drag and drop' (label | dndmedia) in Site administration > Plugins > Text and media area is removed, as there is no reason to disable the functionality.
Maximum number of sections setting deprecated
The setting 'Maximum number of sections' (maxsections) in Site administration > Courses > Course default settings is no longer used in any standard feature. The setting is deprecated and will be removed in a future version. A teacher can add as many sections as they want to their course with no limit.
See also the list of upgrade_notes-labelled issues and ui_change-labelled issues.
New capabilities in Moodle 5.1
- moodle/customfield:configureshared
Moodle 4.3, 4.4, 4.5 and 5.0 upgrading notes
Depending on which version you are upgrading from, please see the section 'Possible issues that may affect you' in the documentation:
Any questions about the process?
Please post in the Installing and upgrading help forum on moodle.org.
- Here’s a video from Rick, a Moodle.org “Helpful Moodler,” demonstrating how he upgraded Moodle 5.0 to Moodle 5.1 on his VPS. It’s captioned in several languages.
Upgrading Moodle 5.0 to Moodle 5.1 on a VPS - Rick demonstrates upgrading three of his Moodle sites in under 10 minutes using the method described in the above video, "Upgrading from Moodle 5.0 to Moodle 5.1 on my VPS video.
Update 3 Moodle Sites in Under 10 Minutes
