Migrating Moodle Courses Between Major Releases: Backup, Restore, and Verification

The problem with cross-version Moodle restores

Youve exported a course from Moodle 3.9 and now need it on Moodle 4.2. The built-in backup tool creates a .mbz file, but restoring it across major versions isnt always straightforward. Plugin version mismatches, enrolment plugin gaps, and PHP memory limits can turn a simple restore into a debugging session.

Step 1: Audit the backup before you move it

Moodle backups bundle course content, grading schemes, and plugin settings into a single archive. When the source and target runs differ major versions, the archive may reference plugin versions that arent installed or are marked incompatible on the new site. Additionally, the Restore wizards default Restore option overwrites an existing course, which can erase existing activities if youre not careful.

Step 2: Restore on a staging instance using Add mode

Never restore directly into a production course until youve validated the process on a copy. Use the Moodle Restore wizards Add option; this merges the backup into the target course without deleting existing activities. To create a backup via the command-line interface, run from the server where Moodle is installed, as the web server user (e.g., www-data or apache), with the moodle data directory writable:

cd /var/www/moodle
php admin/tool/backup/cli_export.php --courseid=12 --backupid=20240101

The command requires the moodle user to have read access to the course directory and write access to the /backup folder. Expected checks after the command finishes include verifying that the .mbz file appears in the /backup directory and that the terminal log shows Backup completed successfully. Relevant risks: if PHP memory_limit is too low, the process may terminate prematurely; adjust phpini or use the Moodle admin UIs chunked backup option for large courses.

Step 3: Verify what survived

1. Activity and resource count – compare the number of activities listed in the course summary before and after the restore. Look for missing labels or broken links.
2. Gradebook entries – open the gradebook and confirm that graded items, categories, and user scores match the source course.
3. Enrolment and role assignments – check that users who were enrolled in the source course appear with the same roles on the target.
4. Corruption check – run Moodles built-in tool under Site administration Server Check for corruption after restore.

Limitations and how to check them

Incompatible plugins – even after auditing, a plugin may have API changes between major versions that cause the restore to silently skip content. The practical check is to compare the activity types listed in the backups plugin manifest against the targets plugin list.

User enrolments may not transfer – if the source course used an enrolment plugin that isnt installed on the target, enrolled users will lose access. After restore, navigate to Site administration Users Enrolled users and filter by the course; missing users signal a plugin gap.

Large backups and PHP limits – a backup exceeding the PHP memory limit will fail partway through. If you see Maximum execution time exceeded in the log, switch to chunked backup mode in the UI or increase memory_limit and max_execution_time in phpini.

Restoring into an existing course overwrites data – the Restore option replaces the course entirely. Always use Add or rename the target course before restoring.

Closing: a repeatable migration checklist

1. Back up a single test course on the source Moodle.
2. Note every plugin referenced in the backup manifest.
3. Update or replicate those plugins on a staging Moodle running the target major version.
4. Restore the backup using the Add mode on the staging instance.
5. Run the activity count, gradebook, enrolment, and corruption-check verifications.
6. Only proceed to production once all checks pass.