Commonsense WordPress Site Migration
WordPress site migrations are not easy. In fact, without additional tools, “migrate a site to another URL” is probably one of the most technical jobs that a WordPress site administrator might commonly perform.
I started writing this article as a walkthrough for doing the process yourself. That piece remains in there, but I also finally took the time to try out some plugins that do the job for you. They’re surprisingly good; one in particular, All-in-One WP Migration, is dead-simple and does the whole job quickly and for free. My overall conclusion is that, with it or something similar around, you generally don’t need to do manual site migrations except in special circumstances. Instead, rely on a good plugin and you’ll save yourself a lot of time and potential complexity.
Learning to migrate WordPress sites will teach you a lot about WordPress itself.
But it’s still good to know how to do it yourself! When the power goes out, it’s really nice to know how to use kerosene lamps. Similarly, you should understand WordPress site migration, lest you need to do it without plugins to save you. Learning the ins and outs of migrating WordPress sites will also teach you a lot about WordPress itself. We’ll take a look at that process later in the article.
What a WordPress site migration means
Migrating a site means moving it from one url to another. For example, you might want to move a site from
That’s the goal. How you accomplish this in WordPress isn’t as easy as just copying a plain-HTML site from directory to directory, because, unlike plain-HTML sites, WordPress sites are made up of two pieces:
- The filesystem, which contains the WordPress software itself, as well as your WordPress theme, plugins, and media files (like pictures).
- The database, which contains most site data: all your posts, users and passwords, content types, permalink settings, and so forth.
To move a WordPress site, you have to migrate both the files and the database.
You have to migrate both the files and the database. A site without a database is like a supermarket with no food: everything’s set up to display the contents, but there are no contents. A database without a site is like a huge pile of supermarket food by the side of the road: the contents are all there, but there’s no sane way to display them. Neither of these setups is going to work. So to move a WordPress site, you need to move both the files and the database.
What’s more, you need to make sure that the files are communicating properly with the database—meaning, at a minimum, that your
wp-config file has the right database information, and that your
.htaccess rules aren’t causing trouble. (Those two pieces cause a lot of the complexity of a site migration. We’ll talk about them more in “Doing it yourself,” at bottom.)
Plugins: Easy, safe, fast, and hopefully free
All-in-One WP Migration
This plugin is new and obscure, but in my opinion it’s the way to migrate WordPress sites.
This plugin does exactly what it says: it does your entire site migration in one easy process. You install the plugin at both your test and live sites, then export a giant zip file from the test site and import it at the live site. When I tried it, it created a perfect copy of the site I was transferring—the whole process took around five minutes and was completely free.
I actually only found this plugin in the process of researching this article: it’s only been around since January, and is still largely under the radar. (I found it thanks to WordPress’s “plugin suggestions” feature—thanks, guys!)
New-kid status aside, in my opinion this plugin is the way to migrate WordPress sites. I plan to use it for every site migration I do unless something comes up.
Just a couple of things to look out for before you use it:
- There’s a maximum upload size when you go to import the all-in-one zip file. Mine was 512 MB, which wouldn’t be that hard to reach on a site with lots of overstuffed themes, giant media files, etc. This limit is set by the plugin authors themselves; they intend to release a commercial version with a 5GB limit.
- There’s a commercial version on the way. It’s unclear how it’ll differ from the free version, but you may find yourself squeezed (for example by the filesize limit above) into paying for the service sometime in the future.
Our sincere advice is to pick up a free version of the plugin now, before the upsell to the commercial version takes effect.
WP Migrate DB
Prior to researching this article, the site migration tool I’d heard about (including in a great in-person presentation) was Brad Touesnard’s WP Migrate DB. WP Migrate DB does the dirty work of exporting and importing your WordPress database, meaning you don’t have to worry about touching phpMyAdmin at all.
This plugin is very popular, but it does have a couple of limitations:
- the full feature set is only available if you purchase WP Migrate DB Pro, which is pricey: $90 per year and up.
- It doesn’t migrate your files by default—only your database. You’ll still need to manually transfer
wp-contentusing FTP. The Pro version has an add-on that lets you migrate media files, but nothing to migrate themes and plugins.
On the plus side, this plugin is solid, established, and around for the long haul. It could be a good choice if you don’t mind the premium price and feel comfortable moving files using an FTP client.
Other plugins, largely premium, offer site migration. It’s commonly bundled with backup plugins (like BackupBuddy and VaultPress), since “site backup” and “site migration” are pretty similar jobs. I haven’t tried these myself, so if you’ve had great luck with one of these plugins (or with another service entirely), I’d love to hear about it!
Doing it yourself: The WordPress warrior’s way
You can do site migrations yourself, but you’ll need a good grasp on several key technologies: FTP, to browse and change your filesystem; phpMyAdmin, to browse, import, and export your database; and searchreplacedb2, Search and Replace, or a similar plugin or script to change database contents. In general, to use FTP you need an FTP client like Filezilla, as well as proper FTP credentials that you can set inside your hosting account; you can access phpMyAdmin directly inside your hosting account; and you’ll have to download and use your database replacer separately. (Note that if you’re moving a site from one host or account to another, you’ll need admin access to both hosting accounts.)
If you’ve never done a WordPress site migration before, I’d suggest looking at this guide. There are a number like it, but this one’s clear.
I’d only make one amendment: You should be able to get away with just moving the
wp-content folder from site to site. That has all your themes, plugins, and media files—and moving only that folder means you don’t have to worry about overwriting
.htaccess, both of which can cause you problems.
We’ll walk through these and other common migration problems in “Gotchas” below.
WordPress migrations often fail in similar ways. As a supplement to the guide we linked to above, here are a list of common migration errors and what they mean.
Errors related to improper
If you copy the entire WordPress install, you’ll overwrite the critical
.htaccess files that sit at the root of every WordPress installation. This will mean the following sorts of errors:
If you get “Error establishing a database connection.” instead of your site, it likely means something’s messed up in
wp-config. It’s quite likely that you copied
wp-config from your test site, and that WordPress is trying to talk to your new database with credentials from your old database. The new database, of course, won’t accept these credentials, so you get an error instead of seeing your site.
If the new layout loads but you still see your old posts, even after importing the database, you might have done the following:
- Imported the database without erasing the old database contents, allowing both sets of database tables to live side-by-side in the database, then
wp-configor otherwise failed to update the database prefix that it looks for.
Basically, you can put multiple WordPress sites in one database, and WordPress tells them apart with a prefix:
wp_ by default, but settable to whatever you like. If you’ve got two sets of tables in your database, they’ve got different database prefixes, and you need to set
wp-config accordingly. For example, if the live site database prefix is
wp-config will need to look as follows to properly display your database contents:
If the homepage loads fine but you can’t properly navigate to any other pages, it likely means something’s messed up in
.htaccess. For example, if you’re moving away from a test site at
testsite.com/testfolder and you overwrote the live site’s
.htaccess in the process, it could look like this:
Those “/testsite” strings are going to screw everything up: they direct all traffic, except homepage visits, to the
/testsite subfolder—which, on your live site, doesn’t exist. Delete
/testsite both places it appears, leaving everything else intact including any remaining slashes and surrounding text, and you should be okay. (Note that the opposite problem is possible if you’re migrating to a subfolder from a site that isn’t in one.)
Errors related to database permalink replacement
This is one of the trickiest pieces of manual site migration. It leads to the following sorts of errors:
If a lot of your links, images, etc. point back to the old test site, it’s a sign you didn’t rewrite permalinks at all. They never got changed, so they still have the old url information in them.
If a lot of links, images, etc. are broken after a permalink rewrite, or if a permalink rewrite causes your site to behave in really strange ways, you may have chosen a rewrite rule that garbled everything in your database—like replacing
livesite.com. The missing slash will bork most of your permalinks and lead to unpredictable and ugly behavior on your site. Erase your database, reimport, and try again. (Yes, it’s that bad.)
Your rewrite rules should be as simple as possible while still being complete. In general, you should rewrite
livesite.com. Don’t include
www, don’t include trailing slashes, etc.: you’re not sure if these are present every time there’s a hardcoded permalink, and you want to replace them all. Conversely, don’t replace
livesite.com if everything actually lived in
testsite.com/testfolder, or the new permalinks will just point everything to the nonexistent
Whew! A lot of information there. If you’re going to be working in WordPress regularly, I’d recommend you learn the ins and outs of site migration. It’s a foundational skill for a WordPress professional, and it’ll also teach you a lot about how WordPress sites are put together.
For day-to-day migrations, though (or if you’re just trying to get the job done once), I’d absolutely recommend you use a plugin, and particularly All-In-One WP Migration. These plugins come and go as WordPress evolves, and plugin authors find ways to push you toward their premium versions, so I’d strongly recommend getting this plugin while it’s up-to-date and free.
Any thoughts, comments, or things we’ve missed? We’d love to hear from you in the comments below!
Image credit: James Hammond