Migrating WordPress from Multisite to Single With MU-Migration

In addition to various commercial plugins, there is one free tool that helps with WordPress migrations to or from multisite installations. MU-Migration is a WP-CLI plugin that worked flawlessly when I wanted to convert helgeklein.com from a multisite into a single site installation. Here are the steps I took.

Migration Overview

When migrating a site with MU-Migration, you perform the following basic steps:

1. Create a ZIP archive of your existing site (in a multisite installation, you can include only one or all sites)
2. Set up a new WordPress site
3. Restore the ZIP archive in the new WordPress site

That is (mostly) it. The remainder of this article covers the steps in more detail and lists additional manual steps I had to perform.

Migration in More Detail

The tool’s GitHub page gives a decent overview of what MU-Migration can do. Start by reading it.

Colorful Tape Drives by Don DeBold under CC

Installing MU-Migration

Make sure you have WP-CLI installed (I did). Install MU-Migration as follows:

wp package install 10up/mu-migration

Creating the Archive

Navigate to your site’s WordPress root directory. Run the following to get the ID of the subsite you want to migrate:

wp site list

To create the backup archive of your source site, run:

wp mu-migration export all ../helgeklein.zip --themes --plugins --uploads --blog_id=ID

This creates the ZIP archive helgeklein.zip with the following contents:

• database export
• directory wp-content/plugins
• directory wp-content/themes
• directory wp-content/uploads
• migration metadata

What is Missing

In my case, I found the following to be missing from the archive:

• Additional directories not part of the WordPress installation (e.g., a downloads directory)
• .htaccess in the site’s root, which may contain custom rewrite rules
• .htaccess in wp-admin, which may contain security hardening restrictions (details)
• favicon.ico
• Google site verification files
• wp-config.php, which may contain custom settings
• W3 Total Cache Configuration in wp-content/w3tc-config

Setting Up a New WordPress Site

First, I created a new database:

mysql -u root -p
mysql> create database wordpress_helgeklein;
mysql> grant all privileges on wordpress_helgeklein.* to "wordpress"@"localhost" identified by "PASSWORD";
mysql> flush privileges;
mysql> exit

As I wanted to perform an “in-place” migration from multisite to a single site, I simply created a new directory public_html_new on the same level as the existing public_html directory. Then I downloaded and extracted WordPress on my client machine, adding the missing pieces to the directory structure that I listed above.

As a next step, I renamed wp-config-sample.php to wp-config.php, transferred some custom settings from the existing wp-config.php over and updated the database connection information with the values I had just configured on the MySQL commandline.

After that, I uploaded the directory structure from my client machine to public_html_new. Then came the most critical part: replacing the old website directory with the new:

mv public_html public_html_old
mv public_html_new public_html

As the last step, I ran WordPress’ installation script from https://helgeklein.com/wp-admin/install.php.

Restoring the Archive

To restore the site archive in your source site, run:

wp mu-migration import all ../helgeklein.zip

With that, your migrated site should be up and running, though some manual steps might still be required.

Manual Steps

In my case, a number of manual steps were still required. I am listing them here briefly for completeness’ sake:

• Enable plugins
• Add entries to .htaccess required by W3 Total Cache
• Add API keys to plugins: UpdraftPlus, Duo Two-Factor Authentication
• Reconfigure plugins: UpdraftPlus

Other Things MU-Migration Can Do

MU-Migration could be useful in many more scenarios than what I described above. For example, did you ever consider setting up a WordPress staging site?