To 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, admin/cli/upgrade.php, purge caches). For Moodle 5.0, point your web root at the new public/ folder and update nginx.
By the numbers
Key takeaways
- Always back up database, moodledata, and code before upgrading.
- Rehearse the upgrade on staging before production.
- Use the CLI: maintenance mode, replace code, run upgrade.php, purge caches.
- Moodle 5.0 moves the web root to a public/ directory — update nginx.
- Verify login, courses, plugins, cron, and logs after upgrading.
- Major upgrades are where small mistakes cost hours — plan rollback.
Before you upgrade Moodle: a pre-flight checklist
A Moodle upgrade is low-risk if you prepare and high-risk if you don't. Before touching anything, work through this:
- ✅ Full backup — database, the
moodledatadirectory, and the codebase - ✅ Check requirements — PHP version, database version, and required extensions for your target release
- ✅ Plugin compatibility — confirm every third-party plugin supports the new version
- ✅ Staging first — rehearse the whole upgrade on a copy before production
- ✅ Maintenance window — enable maintenance mode and tell users
Step-by-step: upgrading Moodle via CLI
The command line is the safest, most repeatable way to upgrade.
- 1. Enable maintenance mode:
php admin/cli/maintenance.php --enable - 2. Back up the database,
moodledata, and current code. - 3. Replace the code — deploy the new Moodle release over a clean copy (don't merge over the old tree), then restore your
config.php, plugins, and themes. - 4. Run the upgrade:
php admin/cli/upgrade.php - 5. Purge caches:
php admin/cli/purge_caches.php - 6. Disable maintenance mode and verify.
The Moodle 5.0 public folder restructure
Moodle 5.0 introduces a public/ directory change to the codebase layout: the web server document root points at the public folder rather than the Moodle root. This improves security by keeping non-public files out of the web root. When you upgrade to 5.x, plan to update your web-server document root accordingly and test that asset and login URLs resolve.
Nginx configuration notes
On nginx, point the root at the new public directory, ensure PHP-FPM handles .php requests, and confirm try_files and pretty-URL rules still work after the move. Reload nginx and test login, course pages, and file serving before reopening to users.
Post-upgrade verification
- ✅ Site loads, login works, and a sample course renders
- ✅ Plugins and theme display correctly (purge caches if not)
- ✅ Cron is running and scheduled tasks complete
- ✅ File uploads and downloads work
- ✅ No errors in the server and PHP logs
Need a hand with your upgrade?
Major-version Moodle upgrades — especially the 5.0 directory change — are where small mistakes cost hours. EdzLMS plans, rehearses, and runs production Moodle upgrades with rollback ready.
Moodle upgrade, step by step
- 1Maintenance mode
Enable it and notify users.
- 2Back up
Database, moodledata, and codebase.
- 3Replace code
Deploy the new release; restore config, plugins, themes.
- 4Run upgrade
php admin/cli/upgrade.php, then purge caches.
- 5Verify
Login, courses, plugins, cron, and logs.
Don't skip this
Always rehearse the full upgrade on staging with a fresh backup ready to roll back — major-version upgrades are where small mistakes cost hours.
Frequently asked questions
How do I upgrade Moodle safely?
Back up the database, moodledata, and code; check requirements and plugin compatibility; rehearse on staging; then run the CLI upgrade and verify before reopening to users.
What is the Moodle 5.0 public folder change?
Moodle 5.0 restructures the codebase so the web server document root points at a public/ directory, keeping non-public files out of the web root for better security.
Can I upgrade Moodle directly to the latest version?
Check the upgrade path — some versions require stepping through an intermediate release. Always confirm PHP and database requirements for your target version.
How do I upgrade Moodle from the command line?
Enable maintenance mode, back up, replace the code over a clean copy (restoring config.php, plugins, themes), run php admin/cli/upgrade.php, then purge caches.
What should I check after a Moodle upgrade?
Login, a sample course, plugin and theme display, cron and scheduled tasks, file upload/download, and server and PHP logs for errors.