Moodle Upgrade Checklist · StackStead Solutions

0/280 of 28 done

01Plan the upgrade

0/7

Note your current versionSite administration › Notifications shows the exact Moodle version and build you are running.
Check you can upgrade directlyMoodle 5.0 and 5.1 can only be reached from 4.2.3 or later, and 5.2 and 5.3 from 4.4 or later. Anything older needs an intermediate upgrade first.
Check the server requirementsRead the target release’s notes for the PHP and database versions it needs, then run Site administration › Server › Environment to check your server against them.
Check every add-on plugin and themeList them under Site administration › Plugins › Plugins overview, then confirm each has a version for the target release in the Moodle plugins directory. Plan a replacement for any that don’t.
Read the upgrade notes for each release you skipReleases remove and change features. Moodle 5.0, for example, removed Chat, Survey and the Atto editor, and moved to Bootstrap 5, which affects custom themes.
Set an upgrade keyMoodle recommends one: it stops anyone else from starting the upgrade from the browser.
Agree a maintenance windowPick a quiet time (not during exams or enrolment), and tell teachers and students in advance.

0/4

Back up the databaseA full dump of the Moodle database (for example with mysqldump or pg_dump).
Back up moodledataThe data directory holds every uploaded file, so it matters as much as the database.
Back up the Moodle codeThe whole code directory, including config.php and every add-on plugin and theme.
Test a restoreA backup you haven’t restored is a guess. Restore it once on another server.

0/4

Clone production to a test serverSame code, a copy of the database and moodledata, and the same PHP and database versions.
Run the full upgrade there firstNote every warning and error, and fix them before touching production.
Test the journeys that matterLog in, open courses, submit an assignment, take a quiz, check the gradebook, enrol a user, and test each integration (single sign-on, payments, video classes).
Time itHow long the copy took tells you how long the production window needs to be.

0/8

Turn on maintenance mode, then let cron finishSite administration › Server › Maintenance mode, or php admin/cli/maintenance.php --enable. Wait for any running cron jobs to end before going further.
Move the old code asideRename the old code directory and unpack the new release in its place. Never unpack a new release over the old files.
Bring back config.php and your add-onsCopy config.php into the new Moodle directory, then add the target-release version of each add-on plugin and theme, in the same place it was before.
Moving to 5.1 or later: update the web serverMoodle 5.1 moved the web-facing files into a public folder. Point the document root at moodle/public and set up routing to r.php, as Moodle’s upgrade guide shows for Apache and Nginx.
Set file permissionsThe code should be readable by the web server but not writable by it. Keep moodledata outside the code folder.
Run the upgradephp admin/cli/upgrade.php, run as the web server user, or log in as an admin and go to Site administration › Notifications. On non-English sites, raise max_execution_time if the browser upgrade times out.
Purge all cachesSite administration › Development › Purge all caches, or php admin/cli/purge_caches.php.
Turn off maintenance modephp admin/cli/maintenance.php --disable. Do a quick check yourself before telling users.

0/5

Check Notifications and cronNo pending upgrades or errors, and scheduled tasks running again.
Review new settings and capabilitiesEach release adds capabilities and changes defaults; check them against your roles and site policy.
Re-test the key journeysThe same checks you ran on the copy, now on the live site.
Watch the logs for a few daysErrors that only appear under real use tend to show up in the first week.
Plan the next upgradeNote when this release’s security support ends, so the next upgrade is planned, not urgent.