How to migrate a multi-site WordPress installation to Pantheon?

A lot of people use the WordPress multi-site feature to build and manage their sites (even does it) as it allows them to have an almost infinite number of web sites in just one installation. This might look like an efficient approach, but it has disadvantages and remember that all that glitters is not gold (see more on

Maybe those are reasons why some famous hosting services don’t let you install multi-site instances inside their platforms (or maybe they also have some profit-oriented ones), but independently of the motives, if you just want to start taking advantage of the benefits Pantheon provides you with, you will need to isolate your sites before being able to deploy them, so that’s this article’s reason for living.

Although this is not intended to be a comprehensive guide, it will give you an overview of the main steps to migrate a WordPress site from a multi-site installation to a Pantheon environment:

1- Take inventory of activated plugins (both on network and site level)

This is necessary for taking your site with just the essential plugins and it might help to fix issues during the deploying process as sometimes you don’t know what network-activated plugins your site was using.

2- Take inventory of site-specific users

In multi-site WordPress, there is just one table storing users for all sites and therefore, when you migrate the database, all existing users will be copied to the new Pantheon instance.

Usually this is not the desired result and you don’t want to preserve users not belonging to your original site, so you will need to remove them manually at the end.

3- Create a clean new single-site Wordpress  instance by using Pantheon web interface

This is a straightforward step thanks to the simplicity of Pantheon. You can go to if you need explanation.

4- Migrate inventoried plugins

To do this, first you will need to clone the Git repository in your own computer or server (such repository is created automatically by Pantheon whenever you set up a new instance).

Then you can copy all the inventoried plugins to the “wp-content/plugins” folder, make a commit and push the changes to the remote repository.

5- Migrate the active theme

Likewise, just copy your site’s current active theme to the “wp-content/themes” folder, make a commit for it and push the changes.

6- Migrate any parent theme (if needed)

Sometimes your current theme descends from another one, so copy all the necessary parent themes (you will find out that in the “Appearance -> Themes” section of your new instance, as you won’t be able to activate a theme without its parents).

7- Migrate uploads directory

To get this done, you will have to find out your site’s ID number first. You can do so by looking at the “Edit” link of the respective site in the “My sites -> Network admin -> Sites” section.

Then you can copy the respective uploads folder to “wp-content/uploads”. For example, if your site’s ID is 15, you should copy all the content from “wp-content/uploads/sites/15/” (in your old instance) to “wp-content/uploads” (in your new instance).

8- Migrate tables (both the site-specific ones and the common ones)

You can recognize your site’s specific tables by their name. They include your prefix and your site’s ID at the beginning. For example, if your configured prefix is “wp_” and your site’s ID is 15, then you will need to copy all tables starting with “wp_15_”.

Additionally, you will always have to copy the two global user tables:

  • wp_usermeta
  • wp_users

Note: you can use “mysqldump” to create database backups on specific tables:

mysqldump -u user -h host -p"password" -n --add-drop-table database_name table1 table2 > backup.sql

And don’t forget to rename tables in order to remove the site’s ID number. For instance:

sed 's/wp_15_/wp_/g' backup.sql > backup2.sql

9- Enable debug mode

Just add the following line to wp-config.php:

define('WP_DEBUG', true);

This might help to find the cause of potential issues.

10- Hard code the new URL in wp-config.php (optional)

Usually Pantheon takes care of this, but if you ever have trouble opening your wp-admin, you can always try to set the URL manually:


11- Check “Media” section

Make sure every single media item was successfully migrated to the new instance.

12- Remove unrelated users

Remove any user not belonging to your site in the “Users” section

13- Run and debug

Finally, run your site in the browser and take into account that it might need some plugins to be activated/deactivated in order to work well, so start the debugging process by activating all the site-specific inventoried plugins (because you are sure they are going to be used) and then try activating/deactivating network-inventoried plugins until you get the desired result.




Do you need some help?

Let's get started. Tell us a little about yourself and your organization
and we can start a conversation about your needs and our capabilities.
Tagged: ,

Related Posts