Moodle Domain Migration: A Complete Step-by-Step Guide

Updated 5 November 2026 · Standard formula, shown below

Moving Moodle to a new domain changes more than the address learners type: Moodle also stores its site URL in configuration and may store old links in the database. This guide covers a full migration to a new domain, including files, database, web server, URL replacement, and post-move checks. Before starting, confirm that you have administrative access to the current and new hosting environments.

What You’ll Need

Administrator or shell access to both servers, or equivalent access through your hosting control panel.
The Moodle code directory, Moodle data directory (often called moodledata), and a database backup.
Credentials and connection details for the destination database.
A web server and PHP environment compatible with your installed Moodle release. Check the requirements for that exact release in Moodle documentation.
Access to DNS and the new domain’s TLS certificate, plus a maintenance window for the final copy.
A way to test the destination before changing public DNS, such as a temporary hostname or hosts-file entry.

Step-by-Step

Record the existing setup. Note the Moodle release, PHP version, database type and version, web server, installed plugins, scheduled tasks, email settings, and paths to the code and data directories. Check config.php for the current $CFG->wwwroot, $CFG->dirroot, and $CFG->dataroot. Keep configuration files private because they contain database credentials.
Plan a compatible destination. Install the same Moodle release and compatible PHP/database versions, or plan an upgrade as a separate, carefully tested project. Do not combine a domain move with an untested Moodle upgrade. Create the destination database and database user, and set suitable permissions. Configure the new web server’s document root to point to the Moodle code directory.
Prepare the new domain. Add the domain to the destination host and configure DNS when you are ready to direct users there. Set up HTTPS and verify that the web server serves the correct virtual host. You can test before public DNS changes by temporarily directing your own computer to the new server, while retaining the correct hostname for TLS testing.
Put the old site into maintenance mode. Announce a maintenance window, prevent new activity, and stop Moodle cron or scheduled tasks on the old server. This avoids losing forum posts, submissions, or other changes made while files and database are copied. Take a fresh database backup and preserve an untouched copy of the original site.
Copy the Moodle code and data. Transfer the code directory and the entire Moodle data directory to the destination, preserving file contents and permissions. The data directory must be outside the web-accessible document root. Do not assume the code directory contains course uploads; they normally reside in the data directory. Keep the same Moodle code version during a domain-only move.
Restore the database. Import the final database backup into the destination database. Confirm that the import completed without errors and that the destination database user can read and write the database. Use a backup and restore method appropriate to the database type; large databases may need command-line tools or hosting-provider assistance.
Update config.php. On the destination, set $CFG->wwwroot to the exact new HTTPS URL, including any required subdirectory. Update $CFG->dirroot and $CFG->dataroot to the destination paths, and change database connection settings to the new database. Do not expose this file or copy it to a public location.
Replace old URLs using Moodle’s tool. With the destination not yet open to learners, run Moodle’s supported CLI search-and-replace tool from the Moodle code directory. For example: php admin/cli/replace.php --search=https://old.example --replace=https://new.example. Use the exact old and new URL forms found in your site, including scheme, hostname, and any path. Check the command’s help for your installed release and review its output. Do not use a basic SQL find-and-replace: Moodle stores some data in formats that require Moodle-aware handling.
Purge caches and check scheduled tasks. Run php admin/cli/purge_caches.php from the code directory. Configure cron on the new server to run Moodle’s scheduled tasks at the interval recommended for your release. Make sure the cron command uses the correct PHP executable and Moodle path; do not leave both old and new servers processing the same live site.
Test before opening the site. Sign in as an administrator and check the site homepage, course pages, uploaded files, images, plugins, login/logout, email, and key learner activities. Review Moodle’s environment checks and server error logs. Confirm that pages load over HTTPS without redirects to the old domain, mixed-content warnings, or missing files.
Switch traffic and monitor. Once testing passes, update public DNS to the destination. DNS changes can take time to reach all users. Keep the old server intact but in maintenance mode during the transition; do not let users submit work to two separate copies. Monitor logs and user reports, then retire the old environment only after you have verified the migration and retained backups.

Common Mistakes

Changing only the DNS record and forgetting $CFG->wwwroot, database links, or the web server’s document root.
Putting moodledata inside the public web directory, or copying only the Moodle code and not the data directory.
Running an incompatible PHP version or changing Moodle versions without testing the upgrade separately.
Using direct SQL replacement for URLs, which can damage serialized data or leave some links unchanged.
Allowing learners to use the old site after the final backup, so new activity is absent from the destination.
Forgetting to move cron, email, plugin configuration, or other server-level settings that are not contained in the database.

Tips

Do a complete trial migration on a staging server before the final move, especially for a large site.
Keep a written record of paths, commands, backup timestamps, and DNS changes so you can repeat or reverse the process.
Use a short DNS time-to-live well before the planned switch if your DNS provider allows it; changing it at the last minute may not affect cached records.
Preserve the old domain and redirect it to the new one only after testing. A redirect does not replace Moodle’s database URL update.
Take backups of both the database and data directory before making changes, and verify that the backups can be restored.

Troubleshooting

If Moodle redirects to the old domain, recheck $CFG->wwwroot, run the Moodle URL replacement with the exact old URL, and purge caches. If you see a blank page or server error, inspect the web server and PHP logs, verify PHP extensions and file permissions, and confirm the database credentials in config.php. If uploaded files are missing, check that $CFG->dataroot points to the copied data directory and that the web server account can read and write it.

For HTTPS warnings or redirect loops, verify the certificate, web server HTTPS settings, and any proxy configuration; make sure Moodle’s URL and the public site agree on HTTPS. If login or course pages fail after a URL replacement, confirm that the search and replacement strings match the site’s actual URLs, then review logs and plugin compatibility. If the migration is incomplete, keep the new site in maintenance mode and restore from the verified backup or repeat the copy rather than allowing activity on both servers.

Frequently Asked Questions

Can I change the domain without moving servers?
Yes. Update the web server and HTTPS configuration, set Moodle’s $CFG->wwwroot, replace stored URLs with Moodle’s supported tool, and test the site. Back up first.

Do I need to change the Moodle database?
Not necessarily. If the database stays on the same server, you may keep its connection settings. You still need a current backup and must update stored URLs where needed.

Can I use a database export and import for the migration?
Yes. A database backup and restore is a common method. Use tools suited to your database and verify the import, character encoding, and database permissions.

Will users need new accounts?
No, not if you migrate the existing database and Moodle data correctly. User accounts and course records are stored in the database; uploaded content is generally in the data directory.

How long should I keep the old site?
Keep it preserved and unavailable for new activity until the destination has been verified and the transition is stable. Retain backups according to your organization’s normal retention practices.

Should I upgrade Moodle during the domain move?
It is safer to separate the changes. First migrate the same Moodle release and confirm the new domain works, then plan and test an upgrade independently.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.