If you manage a Moodle site for a university, college, or business training platform, this guide explains how to upgrade safely to Moodle 5.1 (or later), configure your hosting to use the new folder structure, and ensure your site remains stable through future upgrades.

About This Guide

This guide is based on real-world upgrades tested on managed VPS and local development environments. Specific steps may vary depending on your hosting provider or IT setup, but the principles apply broadly to all Moodle installations hosted on standard Linux-based environments.

What’s New in Moodle 5 (and Beyond)

• New folder structure:
  From Moodle 5.1 onwards, the /public/ folder is the only directory served by the web server. Web-accessible code, including themes and third-party plugins, resides under /public/, while sensitive or core directories such as admin, lib, and files like config.php are stored outside /public/ for improved security. ( Moodle Docs )


• Improved security:
  Separating public and private code paths helps prevent direct access to critical files.


• Cleaner upgrades and deployments:
  The new structure simplifies future updates and automated deployments by separating public code from private files — a change designed to support more flexible deployment and CI/CD setups. ( Moodle Docs )


• Compatibility updates:
  Moodle 5 supports PHP 8.3+, MySQL 8.4 / MariaDB 10.6+, and other modern dependencies.

For a deeper look at new features, see our related posts:
What’s New in Moodle 5.1 (UI and UX Improvements You’ll Notice)
Moodle 5: What’s New for Course Creators and Why Bootstrap 5 Matters

Step 1. Pre-Upgrade Preparation

1. Back up everything
   • Moodle database
   • Full codebase
   • moodledata folder
   • config.php file
2. Check requirements
   Confirm your server meets Moodle 5’s requirements (PHP 8.3+, MySQL 8.4 / MariaDB 10.6+, HTTPS).


3. Switch to Moodle’s default theme (Boost) before upgrading
   Before replacing any files, log in as an administrator and switch your active theme to Boost — Moodle’s default theme. This prevents upgrade errors that can occur when a custom or outdated theme isn’t compatible with the new version.
   
   
   For more details on safely updating themes, see our post: How To Upgrade Premium Moodle Themes
   .
4. Remove or update non-core plugins
   • Delete any custom plugins you no longer need.
   • Check the Moodle plugins directory to ensure your remaining plugins are compatible with Moodle 5.1 or higher.
   • Only reinstall plugins after confirming compatibility.
   If your current theme or plugins haven’t been updated for Moodle 5.1 yet, this is a great opportunity to modernize. Our premium Moodle 5 themes Lumo, Maker, and Edutor are fully compatible with Moodle 5.1+ and the new /public/ folder structure.
5. Set up a staging copy
   Always test the upgrade on a staging or development site before applying it to your live Moodle instance.

Step 2. Replace the Moodle Codebase

1. Enable maintenance mode.
2. Remove old Moodle files except for:
   • config.php
   • Any plugins you’re keeping
   • The moodledata directory
3. Upload or extract the new Moodle 5.x files.
4. Move your existing config.php file back into place.

Step 3. Update the Folder Structure

In Moodle 5.1 and later, your site must be served from:

/moodle/public/

not from the root Moodle directory. This step is essential. If your document root isn’t updated, Moodle will not load correctly. ( Moodle Docs )

How to Point Your Site to the /public/ Folder

After upgrading, Moodle 5.1 expects your web server to serve files from the new /public/ directory instead of the root Moodle folder. How this is configured depends on your hosting setup.

Managed VPS or University Servers

If you have access to your web server configuration, update the document root to point directly to Moodle’s /public/ folder. For example:

# Apache example
DocumentRoot /var/www/moodle/public

# Nginx example
root /var/www/moodle/public;

Restart Apache or Nginx after saving the changes.

Shared or Managed Hosting

On shared or managed hosting platforms where you can’t directly change the document root, there are a few supported options:

• Create a symbolic link (symlink) to Moodle’s /public/ directory. Example:

ln -s /path/to/moodle/public /path/to/webroot/moodle

This command links your web-accessible directory to Moodle’s /public folder. You can then point your domain to the symlink path in your hosting control panel.

• Use a location-specific alias if your hosting control panel supports it.
• Copy the contents of /public/ into your existing web root (/public_html/) as a last resort.

Reference: Moodle Docs – Shared Hosting (Upgrading)

Cloud Hosting (AWS, Azure, GCP)

In cloud or containerised environments, set your deployment root (for example /var/www/html) to /public. This structure works seamlessly with CI/CD pipelines and automated deployments.

Local Development

In local setups such as MAMP Pro, point your site’s document root to the /public/ folder so it mirrors production behavior.

Step 4. Run the Upgrade

Once your files and folder structure are in place, you can start the upgrade process.

Upgrade via the browser (recommended)

1. Log in to your Moodle site as an administrator.
2. Navigate to Site administration → Notifications, or visit:
   https://yourmoodlesite.com/admin/
3. Moodle will automatically detect the new version and guide you through the upgrade steps.
4. When the process is complete, purge caches via:
   Site administration → Development → Purge all caches

For large or automated deployments, Moodle also provides a command-line upgrade option.
See the official documentation for details: Moodle Docs

Step 5. Verify the Upgrade

• Log in and confirm course pages load correctly.
• Check file uploads, messaging, and cron jobs.
• Ensure your chosen theme displays correctly across devices.

Step 6. Troubleshooting Quick Reference

Step 7. Prepare for Future Releases

The new /public/ structure is here to stay. Keep your site upgrade-ready by:

• Maintaining a staging site for testing.
• Keeping all plugins up to date.
• Using Git or version control.
• Monitoring Moodle Releases.

Bonus Tip: Modernize Your Site While You Upgrade

Upgrading to Moodle 5 is the perfect opportunity to refresh your LMS design. Our Lumo, Maker, and Edutor themes are built on Bootstrap 5, fully compatible with Moodle 5.1+ and optimized for accessibility and mobile learning.