Upgrading to Moodle 5.1 or later is slightly different from previous versions, mainly due to the introduction of the /public/ folder structure. If you’re wondering how to upgrade safely, this guide walks you through the process step by step.

This guide applies to upgrades from Moodle 4.x or 5.0 to Moodle 5.1 and later versions, where the new /public/ folder structure requires changes to your hosting setup.

What’s New in Moodle 5.x

• New folder structure:
  From Moodle 5.1 onwards, the /public/ folder is the only directory served by the web server. Web-accessible code, including core components, themes, and third-party plugins, now 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 modern PHP and database versions (for example PHP 8.3+ and recent MySQL / MariaDB releases), depending on the specific Moodle version.

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, before upgrading. 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 and later versions.
   • 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 later versions, including 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.
   
   

   Note for customers using our premium Moodle themes:
   A single-application license allows you to install the theme on both a staging/development site and your public-facing production site. This makes it easier to test your upgrade safely before applying changes to your live Moodle installation.

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

This structural change is the main difference when upgrading from Moodle 4.x or 5.0, and is often where configuration issues occur.

From Moodle 5.1 onwards, your site should be served from:

/moodle/public/

not from the root Moodle directory. This step is required for most standard setups. 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 creates a link from 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 release updates.

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.