Upgrading Your Moodle Site: A Comprehensive Guide

Upgrading your Moodle instance is a critical maintenance task that ensures you benefit from the latest features, security updates, and performance improvements. This guide provides a detailed walkthrough of the Moodle upgrade process, ensuring a smooth transition to the newest version. Whether you are staying on the same server or planning to move your Moodle theme to a new server as part of a broader migration, understanding these steps is essential.

Preparing for Your Moodle Upgrade

Before initiating the upgrade, careful preparation is crucial to minimize potential disruptions and ensure data integrity.

Check System Requirements

Verify that your server environment meets the minimum requirements for the target Moodle version. You can find these requirements in the Moodle 4.5 release notes and within your Moodle site itself under Site administration > Server > Environment. Pay close attention to the necessary PHP version, database type and version, and server extensions.

Backup Important Data

Prior to any upgrade, backing up your entire Moodle site is non-negotiable. This safeguards your data in case of unforeseen issues during the upgrade process. There are three key areas to backup:

Moodle Software: This includes all the core Moodle program files. Typically, this is located in a directory like /server/htdocs/moodle.
Moodle Uploaded Files (moodledata): This directory stores all user-uploaded content, course files, and other essential data. It’s usually located outside the main Moodle software directory, for example, /server/moodledata.
Moodle Database: This is where all your Moodle site’s data, including courses, users, assignments, and settings, is stored. Use your database administration tools (like phpMyAdmin, or command-line tools for MySQL or PostgreSQL) to create a full database dump.

Refer to the Site backup documentation for more in-depth guidance on backup procedures.

Check for Plugin Updates, Including Themes

Moodle’s functionality is often extended through plugins, and themes customize the look and feel of your site. Before upgrading Moodle, it’s vital to check for updated versions of all installed plugins and themes compatible with your target Moodle version.

Navigate to the Moodle Plugins directory and search for updates for your installed plugins (including themes). Download the updated plugin and theme packages. These will be installed in a later step.

If automatic updates are enabled via Automatic updates deployment, you can streamline plugin updates during the upgrade process itself.

If an outdated plugin or theme causes upgrade issues, you can resolve it by deleting the plugin/theme code from the server file system (rather than uninstalling through Moodle) to preserve associated data.

Put Your Site into Maintenance Mode

Enabling maintenance mode is a crucial step to prevent users from accessing the site during the upgrade, avoiding potential data inconsistencies. Access the maintenance mode settings within Moodle to activate it. Ensure any running cron jobs are completed before proceeding with the upgrade. This prevents interruptions and ensures a clean upgrade process.

Performing the Moodle Upgrade

With preparations complete, you can now proceed with upgrading the Moodle software itself.

Install the New Moodle Software

Download the latest Moodle version from Moodle downloads. Choose the appropriate package (ZIP or TGZ) for your server environment.

Standard Installation Package Steps:

Rename the Old Moodle Directory: Rename your existing Moodle software directory (e.g., from moodle to moodle.backup). Crucially, do not overwrite your old files.
Extract the New Moodle Package: Unzip or unpack the downloaded Moodle package into the location where your old Moodle software was previously installed. This will place all the new Moodle program files in the correct directory. Moodle will handle necessary database and moodledata adjustments during the upgrade process.
Restore config.php: Copy your backed-up config.php file from your old Moodle directory (moodle.backup) to the new Moodle directory. This file contains essential database connection and site configuration settings.
Install Updated Plugins and Themes: If you downloaded updated versions of plugins and themes, copy them to the appropriate directories within the new Moodle code structure now. Ensure you are using versions compatible with your new Moodle version. Place plugin folders in the same locations they were in your previous installation to avoid issues. For themes, this is typically the /theme/ directory.
Moodledata Location: Your moodledata directory should ideally be located outside your Moodle code directory and should remain untouched during this process. If you are moving your Moodle theme to a new server as part of a server migration, ensure the moodledata path in your config.php is correctly updated to reflect its new location. Refer to the Migration documentation for server migration specifics.

Example using Linux Command Line:

mv moodle moodle.backup
tar xvzf moodle-latest-4.5.tgz

Next, copy over your config.php, custom plugins, and any .htaccess file you might have created (ensure plugin and theme versions are compatible with the new Moodle version):

cp moodle.backup/config.php moodle
cp -pr moodle.backup/theme/yourcustomtheme moodle/theme/yourcustomtheme
cp -pr moodle.backup/mod/yourcustommodule moodle/mod/yourcustommodule

Set appropriate permissions for the Moodle directory to ensure your web server can access the files, but for security, they should not be writable by the web server:

chown -R root:root moodle  # Adjust user/group as needed for your system
chmod -R 755 moodle

Using Git for Upgrades

For more advanced users, Git can be used for updating or upgrading Moodle. Consult the Git for Administrators documentation for detailed instructions.

Command Line Upgrade

On Linux servers, Moodle 4.5 and later versions support running the upgrade from the command line. This method is generally more reliable, especially for larger Moodle sites, as it bypasses web browser timeouts and limitations.

Finishing the Upgrade

The final step is to trigger the database upgrade process within Moodle.

Remove your site from Maintenance mode. Then, access your Moodle site through a web browser and navigate to Site administration > Notifications.

Moodle will automatically detect the new version and initiate any necessary SQL database or file system upgrades. Follow any on-screen instructions. In rare cases where manual steps are required, Moodle will provide specific messages.

Once the upgrade completes without errors, your new Moodle version is ready!

Post-Upgrade Steps:

Purge Caches: If you experience any inconsistencies or missing functionality (like the file picker not loading), manually purge all caches via Site administration > Development > Purge all caches. This is particularly important in multi-server environments.

Troubleshooting: “Fatal error: Maximum execution time…”

If you encounter a “Fatal error: Maximum execution time of 30 seconds exceeded” during the upgrade, especially on servers using non-English default languages, increase the max_execution_time in your php.ini file (e.g., to max_execution_time = 160). Alternatively, temporarily switch your Moodle site’s default language to English before upgrading and revert back afterward. See this forum discussion for more details.

Key Updates in Moodle 4.5

Moodle 4.5 introduces several notable enhancements:

AI Subsystem: A new framework for integrating AI tools into Moodle, supporting various LLM providers like OpenAI and Azure. See AI subsystem for details.
Course Subsections: Teachers can now organize course content into subsections for improved structure. Enable this in Site administration > Plugins > Manage activities.
Screen Recording: An additional “Screen” recording option is available in the RecordRTC recorder. Configure it in Site administration > Plugins > RecordRTC.
New Student Notifications: Enhanced notifications for students, including assignment due dates, upcoming quizzes, and overdue assignments.
Assignment Default Grade Settings: Admins can set default grade types and scales for new assignments in Site administration > Plugins > Assignment settings.
Bulk Cohort Deletion: Cohorts can now be deleted in bulk via Site administration > Users > Cohorts.
Organization Type in Site Registration: You can now specify your organization type during site registration.
Option to Hide Manual Login Form: For sites using alternative authentication methods, the manual login form can be hidden in Site administration > Plugins > Manage authentication.

Remember to review the upgrade_notes-labelled issues and ui_change-labelled issues and the Moodle 4.5 developer update for a comprehensive overview of changes.

Questions?

For any questions regarding the upgrade process, please post in the Installing and upgrading help forum on moodle.org.