To upgrade Moodle safely: back up the database, moodledata and code; check PHP, database and plugin compatibility; rehearse the whole thing on staging; then run the CLI upgrade — maintenance mode on, replace the code cleanly, run admin/cli/upgrade.php, purge caches, verify. For Moodle 5.0 specifically, point your web-server document root at the new public/ folder and update your nginx config. The golden rule: major upgrades are where small mistakes cost hours, so prepare a rollback before you start. edzlms handles 5.x upgrades end to end.
Key takeaways
- Always back up the database, moodledata and codebase before upgrading.
- Rehearse the full upgrade on a staging copy before touching production.
- Use the CLI: maintenance mode, replace code cleanly, run upgrade.php, purge caches.
- Moodle 5.0 moves the web root to a public/ directory — update nginx accordingly.
- Verify login, courses, plugins, cron and logs after upgrading.
- Plan a rollback — major upgrades are where small mistakes cost hours.
Before you upgrade Moodle: a pre-flight checklist
A Moodle upgrade is low-risk if you prepare and high-risk if you don't. The failures that eat an afternoon are almost never the upgrade command itself — they're a missing backup, an incompatible plugin, or a PHP version mismatch discovered halfway through. Work through this before you touch anything.
- Full backup — the database, the moodledata directory, and the codebase. All three, or your rollback isn't real.
- Check requirements — the PHP version, database version and required extensions for your target release.
- Plugin compatibility — confirm every third-party plugin supports the new version; an unmaintained plugin is the most common upgrade blocker.
- Staging first — rehearse the whole upgrade on a copy so production is the second time you've done it, not the first.
- Maintenance window — enable maintenance mode and tell users when.
- 1Enable maintenance mode
php admin/cli/maintenance.php --enable — stop writes before you start.
- 2Back up everything
Database, moodledata and the current code tree, so you can roll back cleanly.
- 3Replace the code
Deploy the new release over a clean copy — don't merge over the old tree — then restore config.php, plugins and themes.
- 4Run the upgrade
php admin/cli/upgrade.php, then php admin/cli/purge_caches.php.
- 5Disable maintenance & verify
Check login, courses, plugins, cron and logs before reopening to users.
The Moodle 5.0 public/ folder restructure
Moodle 5.0 introduces a change to the codebase layout: a public/ directory becomes the web server's document root, instead of the Moodle root. This is a security improvement — it keeps non-public files out of the web root — but it's also the step that catches people out on a 5.x upgrade, because login and asset URLs break until the server config is updated.
On nginx, point root at the new public/ directory, reload, and test that login and static assets resolve. The same principle applies on Apache via your document-root directive. Always confirm URLs resolve on staging before doing it in production.
If you're choosing how to run Moodle in the first place, see Moodle deployment options; for what's new in the latest release, see Moodle 5.2.
How edzlms helps: edzlms is a Moodle-based platform with two AI layers — edzlms AI and Gelato. We run Moodle 5.x upgrades end to end — backup, staging rehearsal, the public/ restructure, plugin compatibility and post-upgrade verification — so you get the new version without the downtime risk.
Need something custom-built?
Want custom Moodle plugins, workflow automations, custom reports, activity modules or AI agents built around your team's exact process? edzlms designs and builds it for you. Book a free demo or email marketing@edzlms.com and we'll scope it with you.
Upgrading without prep
- No tested backup or rollback
- Surprised by plugin breakage
- public/ change breaks URLs
- Hours lost in production
The safe CLI approach
- Three backups, tested rollback
- Staging rehearsal first
- Server root updated for 5.0
- Verified before reopening
Pro tip
Deploy the new release over a clean copy and restore config.php and plugins — never merge new code over the old tree. Leftover files from old versions cause the strangest upgrade bugs.
Frequently asked questions
How do I upgrade Moodle safely?
Back up the database, moodledata and code; check PHP and plugin compatibility; rehearse on staging; then run the CLI upgrade (maintenance mode, replace code, upgrade.php, purge caches) and verify before reopening.
What changed in Moodle 5.0's folder structure?
Moodle 5.0 moves the web root to a public/ directory for security. You must point your nginx or Apache document root at public/ and test that login and asset URLs resolve.
Should I upgrade via CLI or the web installer?
CLI is the safest and most repeatable: maintenance mode, replace code, run admin/cli/upgrade.php, then purge caches. It avoids browser timeouts on large sites.
Do I need to back up before upgrading?
Yes — the database, moodledata directory and codebase, all three. Without a complete backup you have no real rollback if something fails.
Can edzlms handle the upgrade for me?
Yes. edzlms runs Moodle 5.x upgrades end to end, including the public/ restructure, plugin compatibility and post-upgrade verification.
See edzlms in action
Book a 45-minute demo and we'll talk through your Moodle upgrade path.