Upgrading Moodle

Upgrading Moodle

Keeping your Moodle installation up to date is essential for security patches, bug fixes, and new features. This guide covers the complete upgrade procedure for Moodle 4.x/5.x.

Before You Upgrade

Preparation is the most critical phase of any upgrade. Failing to prepare properly can result in data loss or extended downtime.

Pre-Upgrade Checklist

• Check version compatibility: Review the release notes for the target version at docs.moodle.org. Verify PHP version requirements, database version requirements, and any deprecated features.
• Check plugin compatibility: Visit the Moodle plugins directory to verify that all installed third-party plugins support the target Moodle version. Disable or remove incompatible plugins before upgrading.
• Full backup: Create a complete backup of all three Moodle components:
  1. The Moodle code directory (e.g., /var/www/moodle)
  2. The Moodle data directory (e.g., /var/moodledata)
  3. The database (using mysqldump or pg_dump)
• Test in staging: If possible, perform the upgrade on a staging or test environment first.
• Notify users: Inform users of the planned downtime.

Creating Backups

Database backup for MySQL/MariaDB:

mysqldump -u root -p --single-transaction --quick moodle > moodle_backup_$(date +%Y%m%d).sql

Database backup for PostgreSQL:

pg_dump -U moodleuser moodle > moodle_backup_$(date +%Y%m%d).sql

Code and data backup:

tar czf moodle_code_$(date +%Y%m%d).tar.gz /var/www/moodle
tar czf moodledata_$(date +%Y%m%d).tar.gz /var/moodledata

Upgrade Procedure

Step 1: Enable Maintenance Mode

Put the site into maintenance mode to prevent users from accessing it during the upgrade:

php admin/cli/maintenance.php --enable

Alternatively, enable it from Site administration > Server > Maintenance mode.

Step 2: Replace the Moodle Code

Using Git (recommended):

cd /var/www/moodle
git fetch origin
git checkout MOODLE_405_STABLE
git pull

Using a download:

mv /var/www/moodle /var/www/moodle_old

Extract the new Moodle version to /var/www/moodle, then copy your config.php from the old directory:

cp /var/www/moodle_old/config.php /var/www/moodle/config.php

Step 3: Run the Upgrade

Execute the upgrade script via the command line (strongly recommended over web-based upgrade for large sites):

sudo -u www-data php admin/cli/upgrade.php

The script will detect the current and target versions, display the required upgrade steps, and ask for confirmation. Add --non-interactive for automated upgrades.

Alternatively, visit https://yourmoodle.example.com/admin in your browser to run the upgrade through the web interface.

Step 4: Update Third-Party Plugins

After upgrading the core, update any third-party plugins. If you manage plugins via Git submodules, pull the updated versions. Otherwise, download compatible versions from the Moodle plugins directory.

Step 5: Disable Maintenance Mode

php admin/cli/maintenance.php --disable

Step 6: Verify the Upgrade

• Check Site administration > Notifications for any pending upgrades or issues
• Verify the version number under Site administration > General > Notifications
• Test core functionality: login, course access, assignments, quizzes
• Check the cron job is still running properly
• Review error logs for any new warnings or errors

Major Version Upgrades

When upgrading across major versions (e.g., 3.11 to 4.0, or 4.x to 5.0), be aware that:

• You must upgrade sequentially through each major version if jumping multiple versions
• Some plugins may not yet have compatible versions
• Theme changes may be significant, especially when moving to Moodle 4.0+ with the Boost-based navigation
• Database schema changes may take longer on large databases

Troubleshooting Upgrade Issues

• White screen after upgrade: Check PHP error logs, increase memory limit
• Database errors: Restore from backup and try again, or check for corrupted tables
• Plugin conflicts: Disable problematic plugins via the database by setting their version to the expected value or removing them from config_plugins