Planning a Moodle Upgrade: Versions, Plugins and Testing

A Moodle upgrade rarely fails because of Moodle itself. It fails on a plugin with no release for the new version, a database server one version too old, or a theme that overrides a template core has since rewritten. Every one of those can be found weeks before upgrade night.

This is the planning sequence we use: fix the target version, check the server, audit the plugins and the theme, rehearse on a copy, then run the real thing in a set order.

Pick the target version first

Moodle ships a major release every six months, in April and October. Each one gets bug fixes for a year and security fixes for six months after that. About every two years a release is marked long-term support (LTS) and receives security fixes for three years. In October 2026 the supported versions are:

Version	Released	Bug fixes until	Security fixes until
4.5 (LTS)	October 2024	October 2025	October 2027
5.1	October 2025	October 2026	April 2027
5.2	April 2026	April 2027	October 2027
5.3 (LTS)	October 2026	October 2027	October 2029

Dates move as new versions arrive, so confirm them on the Moodle releases page before you commit to a plan. A version that is not listed there as supported no longer receives fixes of any kind, and getting off it is the priority.

Two rules shape the route. The first is the minimum starting version. Each release states the oldest version it can be upgraded from: Moodle 5.3 accepts 4.4 or later, and 4.5 accepts 4.1.2 or later. A site on 4.1 therefore goes to 4.5 first and then to 5.3, and each hop is a full upgrade with its own testing.

The second is a structural change. Moodle 5.1 moved every web-accessible file into a public folder. The web server's document root has to point at that folder, config.php stays in the Moodle root, and additional plugins go into the matching folders under public. If your route crosses from 5.0 or earlier to 5.1 or later, the virtual host configuration changes on upgrade night.

Check the server against the release notes

Open Site administration > Server > Environment. The page tests the server against the requirements of your current version and of newer ones, and flags anything that falls short. Then read the requirements section of the release notes for the target. The Moodle 5.3 release notes, for example, ask for:

• PHP 8.3 as the minimum, with 8.4 also supported, 64-bit only;
• the sodium extension, and max_input_vars set to 5000 or more;
• PostgreSQL 17, MySQL 8.4, MariaDB 11.4 or SQL Server 2019 as the oldest accepted databases.

Database minimums rise more often than people expect, and a server that ran the previous release without complaint can fail this check.

Do not assume a PHP branch newer than the ones the notes name will work. And treat a PHP or database upgrade as a separate change: make it first, on a Moodle version that supports both the old and the new server software, and let it run for a week or two before you touch Moodle. On a 4.5 to 5.3 route that means moving to PHP 8.3, which both releases support, while still on 4.5. If something breaks, you then know which change caused it.

Audit every additional plugin

Plugins decide the schedule more than anything else. Go to Site administration > Plugins > Plugins overview, switch to the additional plugins view and put every row in a spreadsheet. For each one, answer three questions:

• Is there a release for the target version? Check its page in the Moodle plugins directory. The plugin's version.php may also declare a $plugin->supported range.
• Is it still used? Ask the people who teach. Old sites carry blocks and activity types nobody has opened in years.
• Who maintains it? A community plugin with recent releases is one thing. A plugin written for you by a developer who has moved on is another.

Each plugin then lands in one of three piles. Those with a compatible release get updated. Those nobody uses get uninstalled from the Plugins overview page before the upgrade, which removes their tables and settings cleanly. Deleting the folder alone does not.

The third pile is the hard one: plugins in use with no compatible release. Moodle's own guidance is that such a plugin has to be updated or uninstalled before you upgrade, and uninstalling deletes its data. If that plugin holds issued certificates or attendance records, you wait for a release, move to an alternative, or have the plugin patched. For custom code, set debugging to DEVELOPER on the staging copy and click through every screen the plugin owns. Deprecation notices tell you what will stop working. Our guide to Moodle plugin types explains what each kind of plugin touches, and patching them is routine Moodle plugin development work.

Treat the theme as the riskiest plugin

Most custom themes are children of Boost that add SCSS, override Mustache templates and sometimes replace renderers. A template override keeps working after an upgrade in the worst possible way: the page renders, but everything core changed in that template is hidden behind your old copy. New buttons do not appear and accessibility fixes are lost.

Before the rehearsal, compare each file in the theme's templates folder with the core template of the same name in the new release. Releases that restyle the interface need more of this work, so read the user interface part of the release notes and allow time for theme changes in the plan.

Rehearse on a copy of production

Build a staging site from a fresh copy of the code, the database and the moodledata directory, on the PHP and database versions the target needs. In the copy's config.php, change $CFG->wwwroot and add $CFG->noemailever = true; so the copy cannot email real learners. Run the upgrade from the command line and time it. Then test what the site exists for:

• login by every method in use, including single sign-on;
• a course page in each course format you run;
• a quiz attempt, an assignment submission and the grading of both;
• the gradebook, completion reports and any custom reports;
• certificates, web service integrations and the mobile app;
• cron, by reading the task logs for failures.

Fix what you find and repeat the rehearsal from a new copy until it runs clean from start to finish. The duration of the last run, plus a margin, is your maintenance window.

Run the Moodle upgrade in a fixed order

1. Announce the window, then enable maintenance mode and wait for running cron tasks to finish. Stop cron.
2. Back up the database, the moodledata directory and the code directory.
3. Move the old code directory aside and unpack the new release in its place. Do not unpack over the old files: leftovers from the previous version cause errors that are hard to trace.
4. Copy config.php back, and copy each additional plugin and the theme into its folder (under public from 5.1 on). If the route crosses into 5.1 or later, switch the web server's document root to public now.
5. If the site uses Composer or has a vendor directory, run composer install --no-dev --classmap-authoritative from the Moodle root.
6. Run the upgrade, purge caches, and check Site administration > Notifications and the Plugins overview for anything still pending or missing from disk.
7. Run the short version of your test list as an administrator, leave maintenance mode, then start cron again and watch its first runs in the task logs.

From the Moodle root, as the web server user, the commands are:

sudo -u www-data php admin/cli/maintenance.php --enable
sudo -u www-data php admin/cli/upgrade.php
sudo -u www-data php admin/cli/purge_caches.php
sudo -u www-data php admin/cli/maintenance.php --disable

The official upgrading guide has the notes specific to each version. Agree the rollback point beforehand. Going back means restoring the database, the old code and moodledata together, because old code will not run on an upgraded database.

When to bring in a developer

A site with a handful of well-maintained plugins, a lightly customized theme and one release to cross is a reasonable job for a capable administrator. The risk rises with distance and with custom code: several major versions behind, plugins nobody maintains, integrations with a student or HR system, a database large enough that the upgrade runs for hours. In those cases most of the effort is patching and testing, which is what our Moodle upgrade service covers. A maintenance plan then keeps the gap from opening again.

Frequently asked questions

How often should a Moodle site be upgraded?

Apply the minor releases for your version as they come out, since they carry the security fixes. For major versions, the slowest safe rhythm is one LTS release to the next, about every two years, finished before security support for the old one ends. Sites with few plugins can follow each six-month release.

Should we stay on LTS versions only?

It suits sites with many plugins, custom code or little time for testing, because you upgrade less often and have three years of security fixes to work with. The cost is that new features arrive later and each jump is larger. Sites with a simple setup lose little by moving every release.

Can a Moodle upgrade skip versions?

Yes, within the limit the target version sets. Its release notes name the oldest version it can upgrade from, and anything older has to pass through an intermediate release first. Check the PHP and database requirements of every stop on the route, not only the last one.

How long will the site be offline?

It depends on the size of the database and how many versions the upgrade crosses. Small sites finish in minutes, and large ones with years of logs and grades can take hours. The only reliable estimate is the time the rehearsal took on a copy of your own data.