How to Upgrade Moodle Without Breaking Your Site

A safe Moodle upgrade is a controlled deployment, not a button click. The reliable sequence is to inventory the site, confirm the supported upgrade path, test a copy, back up all three site components, deploy compatible code, run the database upgrade and verify the result before reopening access.

1. Confirm the supported upgrade path

Check the target release notes and Site administration > Server > Environment. Moodle 5.3 can be upgraded directly only from Moodle 4.4 or later; older sites need an intermediate supported version. Confirm PHP, database, extensions and operating-system requirements.

Upgrading to Moodle 5.1 or later also introduces a major code-layout change: web-accessible files live in a public directory. The web server’s document root must be configured accordingly, and contributed plugins move to their corresponding locations under public.

2. Inventory plugins and customisations

List every contributed theme, activity, block, authentication method and local plugin. For each one, verify a release compatible with the target Moodle version. Record core modifications separately; replacing Moodle code will not preserve informal edits.

Remove an abandoned plugin only after checking how its data will be retained or migrated. A missing compatible version is a reason to delay, replace or isolate the plugin—not to hope production will tolerate it.

3. Rehearse on a staging copy

Clone the database, moodledata and code into an isolated environment. Prevent staging from sending real email, running unintended integrations or exposing personal data. Run the complete upgrade and test login, courses, cron, enrolments, quizzes, reports, scheduled tasks and critical plugins.

4. Take a complete, restorable backup

Back up these three parts at the same point in time:

• The Moodle database.
• The complete moodledata directory.
• The Moodle code, configuration and contributed plugins.

A backup is not a rollback plan until you have tested how to restore it. Note database credentials, DNS or load-balancer steps, filesystem ownership and the expected recovery time.

5. Put the live site into maintenance mode

Announce the window, stop external writes and enable maintenance mode. Administrators can still access the site, so avoid making content changes during the deployment. Pause automated deployment jobs that could change code midway.

6. Replace the code cleanly

Do not overwrite a new Moodle release on top of the old directory. Deploy a clean copy of the target code, then add the existing config.php and compatible contributed plugins in their correct locations. Keep moodledata outside the code and outside the web root.

If the installation is Composer-managed, follow the release documentation and install the required production dependencies before the database upgrade. If it is Git-managed, switch to the intended stable branch or exact tag through the tested deployment process.

7. Run the upgrade

For larger sites, Moodle recommends the CLI process because it is less exposed to browser timeouts:

php public/admin/cli/upgrade.php

Use the path appropriate to your layout and run as the correct service user. Do not refresh or launch a second upgrade while the first is active. Capture the output and investigate every error.

8. Purge caches and verify

After a successful upgrade, purge caches, restart services where your architecture requires it and run cron. Verify the installed version, environment report, plugin overview, scheduled tasks and logs. Test with administrator, teacher and student accounts.

9. Reopen gradually

Disable maintenance mode only after the smoke tests pass. Watch PHP errors, database load, task failures and user reports. Keep the pre-upgrade backup unchanged until the acceptance period ends.

Common mistakes

• Skipping the intermediate version required by the upgrade path.
• Overwriting old code and leaving obsolete files behind.
• Forgetting the Moodle 5.1+ public document-root change.
• Discovering plugin incompatibility after maintenance mode begins.
• Backing up course files but not the database or moodledata.
• Testing only as an administrator.

Final advice

The safest upgrade is boring: rehearsed commands, known durations, complete backups and a written rollback decision. If your theme is the compatibility blocker, compare maintained options at Themes Almond before scheduling the upgrade.

Source check: Verified against Moodle 5.3’s official Upgrading, Git for Administrators and command-line administration documentation.