Moodle Upgrade Guide: Successfully Upgrading Moodle 4.5 to Moodle 5.2 on cPanel

If you’re planning a Moodle upgrade from Moodle 4.5 LTS to Moodle 5.2, this guide will help you avoid many of the common issues that administrators face during the process. I recently completed a production Moodle upgrade on a live learning platform and encountered everything from plugin compatibility issues to inode limitations and the new Moodle public folder structure.

In this article, I’ll share the upgrade process, common challenges, and lessons learned.

Why Upgrade to Moodle 5.2?

Moodle 5.2 offers several improvements over Moodle 4.5, including:

• Better performance and scalability
• Improved security
• Updated user interface
• Enhanced quiz and course features
• Improved PHP 8.3 compatibility
• Long-term support and future plugin compatibility

Keeping your Moodle LMS up to date helps ensure security, performance, and compatibility with modern hosting environments.

Before Starting Your Moodle Upgrade

Before upgrading Moodle, create complete backups of:

Moodle Files

Moodle Code Directory

Moodle Database

Export your database using phpMyAdmin or CLI tools.

Moodledata Directory

moodledata

This contains user files, course content, backups, and cache data.

Config File

config.php

A backup of this file can save significant troubleshooting time.

Check Moodle 5.2 Requirements

Before upgrading, verify:

• PHP version compatibility
• MySQL/MariaDB version
• Required PHP extensions
• Available disk space
• Available inode count
• Cron configuration

One of the biggest issues I encountered was inode exhaustion. Even with sufficient disk space available, the hosting account exceeded its file count limit, preventing uploads and file operations.

Understanding the New Moodle Public Folder Structure

One major change in newer Moodle versions is the introduction of the separate:

public/

directory.

Traditionally, Moodle files were placed directly inside:

public_html

With Moodle 5.x, the recommended structure separates public files from application files for improved security.

Example:

/home/user/moodle52/
/home/user/moodle52/public/
/home/user/moodledata/

What If cPanel Doesn’t Allow Changing Document Root?

Many shared hosting providers do not allow changing the document root of the primary domain.

In my case, the primary domain was locked to:

public_html

The solution was to point the website to the Moodle public directory using a symbolic link or an alternative deployment strategy while keeping the application code outside the web root.

This allows Moodle 5.2 to work correctly without modifying the hosting provider’s restrictions.

Copying Themes and Plugins

After deploying Moodle 5.2, compare the old Moodle installation with the new one.

Common areas to check:

Themes

theme/

Course Formats

course/format/

Blocks

blocks/

Local Plugins

local/

Reports

report/

Quiz Plugins

mod/quiz/accessrule/

Never blindly copy every plugin. Verify Moodle 5.2 compatibility first.

Plugin Compatibility Issues

During this Moodle upgrade, several plugins worked perfectly in Moodle 4.5 but caused issues in Moodle 5.2.

Examples included quiz access plugins that referenced deprecated Moodle APIs.

Common symptoms:

• Quiz failures
• White screens
• Missing functions
• Fatal PHP errors

Always check Moodle.org plugin pages before upgrading.

Running the Moodle Upgrade

Once the new codebase is in place:

php admin/cli/upgrade.php

Follow the upgrade process carefully and resolve any environment warnings before continuing.

Rebuilding Caches

After upgrading:

php admin/cli/purge_caches.php

For custom themes:

php admin/cli/build_theme_css.php

This step is often overlooked but is critical when dealing with theme rendering issues after a Moodle upgrade.

Updating Cron Jobs

Verify your Moodle cron job points to the correct installation.

Example:

/usr/local/bin/php /home/user/moodle52/admin/cli/cron.php >/dev/null 2>&1

Cron should run every minute.

Fixing Stuck Course Restorations

One issue encountered after upgrading was the appearance of multiple courses named:

Course restoration in progress

These were incomplete restore tasks left over from previous operations.

The solution involved:

• Running cron manually
• Clearing temporary backup directories
• Purging caches
• Removing orphaned restore entries

Always confirm with the client that no legitimate courses are missing before deleting these placeholders.

Post-Upgrade Testing Checklist

After upgrading Moodle:

Student Testing

• Login
• Course access
• Quiz attempts
• Assignment submissions

Instructor Testing

• Course editing
• Gradebook
• Course backups
• Course restore

Administrator Testing

• Plugin overview
• Scheduled tasks
• Cron execution
• Reports
• User management

Lessons Learned

A successful Moodle upgrade involves much more than updating files.

Key areas that require attention:

• Hosting limitations
• Plugin compatibility
• PHP version compatibility
• Cron configuration
• Theme updates
• Database integrity
• Course restoration tasks

The actual upgrade may take only a few minutes. The preparation, troubleshooting, and validation often take much longer.

Need Help With a Moodle Upgrade?

I specialize in:

• Moodle installation
• Moodle upgrades
• Moodle migration
• Moodle troubleshooting
• Moodle theme customization
• Moodle performance optimization
• Moodle hosting support

Whether you’re upgrading from Moodle 4.x, Moodle 4.5 LTS, or preparing for Moodle 5.x, careful planning can save hours of downtime and unexpected issues.