Here is how I migrated WordPress content and some thoughts that should not have been afterthoughts. If you found this article on Google because your media library turns out to be empty, I had the same problem (and a solution and that was one of the reasons I wrote this article to share my half knowledge about WordPress migration pitfalls.
Migrating WordPress Content and Configuration
Disclaimer: Of course we can, and probably should, use professional commercial tools to migrate our customers' WordPress content, even more so if it's a large and complex site. This post describes a manual approach that may waste your time and put your data at risk but might help you understand what is actually going on and how to solve some kinds of problems working with WordPress.
In my case, none of this was an issue. It was a very limited scope of content, media and plugins, there was nothing to lose on the target server, and researching and deciding on what plugin to use would have taken me more time than doing the stuff I will describe in more detail here.
What does a WordPress site consist of? When planning to migrate (move or copy) WordPress content, we should not forget WordPress configuration.
Use Case: a Customer Called ...
A customer called me recently. She had set up a domain and webspace for a new business project. Sooner than she had expected, there would be news in the press about her new project, and so she needed content on the new site soon.
As she was about to give up her previous brand in the near future, she planned to copy all of the old content over to the new site where she would subsequently modify.
Prepare and Install
First, let's make sure we are prepared for work, which means we need access to the webspace, file system, and to the existing WordPress installation. And as some systems use two-factor authentication to send verification tokens by mail or messenger before we can actually log in, it's a good idea not to work in the middle of the night unless our customer is awake and ready to communicate.
Many web hosters offer "one-click" installations which are easy-to-use installation wizards providing the latest WordPress version ready to use with a new empty database, an administrator login, and the correct permissions set for uploading images.
We want to test that this actually works: log in to the new administration, upload an image and make sure it displays when we insert it into our first Hello World post.
Inspect and Backup
Then we have to inspect both systems:
- What are the actual domain names and URLs?
- Do both servers use the same (preferably most recent stable) PHP version?
- Do both servers use the same PHP extensions (like OPCache)?
- Does our source system use a fairly recent version of WordPress and its plugins?
- Do the database versions match? (I don't care much about that these days. Any recent mySQL or MariaDB version will usually work very well.)
- Does the new server use a valid SSL certificate to make sure we can use https?
Backup tools are now integrated into WordPress, but beware!
The default backup tool only backs up the default database tables, but not the additional data written by plugins, themes, and page builders. Do you use Yoast SEO, Ninja Forms, Elementor, Divi, Semplice, or any other WordPress extension that might write additional data to the database? Sure you do!
Time to install another plugin: Database Backup for WordPress will back up additional tables as well. Too bad those backups are not WordPress extended XML files, but SQL dumps, so we can't use the built-in data import functionality to restore our data to the target system.
Time to install another plugin, unless the new web hosting provider has a database client installed like adminer or phpMyAdmin. If they didn't, there is a WordPress plugin that provides phpMyAdmin so that we can import our backup data.
Modify Paths in our Backup Files
Let's inspect our SQL dump backup files. We have to replace our old URL (path) with the new one everywhere, to make the content, links, and images work on the new server.
This can be done using the command line or in a visual text editor. If the old source system is really old, there might be different versions of the old URL (with or without
https). We can normalize those links and replace all variations of the old URL with the new one.
Installing Themes and Plugins
Let's inspect our installed plugins and install all plugins on the target system that were active on the source system. We can use the plugin store for a fresh install.
Likewise, we will install the active theme on our new system.
If we have access to the file system, we can use an FTP client like Filezilla to download and upload files (using a secure SFTP connection if possible). In most cases we only need to copy the files in the
uploads folder. Content text, markup, styles, and configuration should be in the database, and plugins, themes and WordPress core system are a fresh install.
Missing Themes and Plugins
Sometimes there are purchased or custom themes, child themes, and plugins, that can't be installed from the official store. We can copy those on the file system as well.
Paid plugins might need a new activation and you might even need an additional license for using it on another domain. But maybe the free versions works good enough to finish and test data migration, so we can leave the contractual business decisions to our customer.
Reparing an empty Media Library
I didn't expect any problems here, but after copying uploaded media files and restoring the database, I found the media library to be empty in the new site WordPress administration.
Googling what to do, I came across many posts of users who had the same problem. They were advised to check the file system permissions etc. which they did and, just like me, still had the same problem.
Time to install another plugin! This is WordPress, if anything does not work, there is a plugin to help. Media from FTP found all of my uploads and somehow registered them somewhere so that they became visible again, ready to use in new posts. Please, WordPress community, this is worth adding to the Frequently Asked Questions: what is happening here and what should the average user do?
At the time of writing, Media from FTP was listed as a popular plugin with a lot of active installations, but also as unmaintained and not checked for compatibility anymore, although it did work fine for me in WordPress 5.9.2 the former maintainers suggested to use another plugin, Moving Media Library or Bulk Media Register, instead.
Recreating User Accounts
We can check, modify, and recreate user accounts manually if they do not match the current requirements. We can send users a password reset email from the user administration panel. Let's make sure our customer has a working administrator login to their new WordPress system before claiming that we finished our work.
Configuring Performance Optimizations
After we are done with any temporary state of content and configuration, let's check our performance optimization. Currently I use two popular plugins to optimize any WordPress installation making it a little faster and more successful with Google and other search engines.
- Yoast SEO enables editors to add relevant meta information that helps search engines and social media sites to find and index their content
Even the free, unpaid versions of both plugins, used with default settings and a little common sense (common at least for me as a web performance specialist, I shall write another article on that subject) can improve page speed and measured core web vitals drastically.
We can make a web page test (using a tool like WebPageTest or Google's PageSpeed Insights which is also available as a Lighthouse performance audit in our browsers developer tools) before and after activating performance settings. We should see an improvement, often taking our page from an initial slow score indicated in red to a better score in yellow (or, rarely, especially for minimalist sites avoiding stupid marketing ideas like auto-play video backgrounds, even a green score above 90/100).
My personal WordPress blog website currently scores 79/100 points in PageSpeed Insights thanks to a modern, minimalist theme and W3 Total Cache optimization. Some even more minimalist customer sites actually made it above 90, but anything above 50/100 is not bad for an average WordPress blog in my experience.
And of course we can craft a website with optimal web performance using modern build tools like JAM stack and use WordPress only as headless CMS or not use it at all. But even in 2022, WordPress is still one of the most popular web publishing systems especially among small businesses, so it does not hurt to have some WordPress knowledge and experience as a web developer.
Test and Communicate
After installation and migration, do some testing by opening the blog home page in a private browser tab, scroll down to the footer, click on random links, and try to use any fancy features like light box image galleries, embedded calendar widgets, or contact forms.
- Does the site load at all?
- Does anything look broken?
- Do images show up?
- Does the site look the same like the original source version?
- Do we see error messages and warnings in our browser developer tools that don't appear on the source version?
- Are images loaded from our new domain? Do links point to the new domain? Make sure we're not taken to the deprecated old site and that we are still testing the new installation.
We don't have to be perfect, after all it's the customer's site and probably there are some adjustments and modifications they plan to do themselves anyway. So before wasting too much time doing menial tasks, tell the customer what we did so far and ask if the require any more service on our behalf.
Finally, Clean Up!!!
Also let's not claim that we finished our work before cleaning up and removing all unnecessary plugins needed only for migrating our data and which might add security risks to our customer's system in the future, especially a powerful tool like phpMyAdmin. Let's deactivate and uninstall
- phpMyAdmin (as a WordPress plugin) on the target system
- Media from FTP (or Moving Media Library), our image library repairer on the source system
- Database Backup for WordPress, our custom backup helper, on the source system
- Hello Dolly, a demo plugin that comes with every new WordPress installation, on the target system
and reset passwords, delete temporary login accounts that are no longer needed (like additional FTP or even SSH accounts) and log out everywhere.
Also, if we used or even saved any actual master logins that belong to our customer, we should delete them forever. But maybe not today. I will rather set up a reminder to delete in two or three days, so I still have a login handy just in case it turns out we messed something up and the customer might need urgent help tomorrow. So, now is tomorrow, and when everything works, don't forget to bill our customer for our work, and delete any passwords still saved on our computer.
While WordPress has improved a lot over the years (at least everything apart from Gutenberg block editor, but that's only my personal opinion as a web developer who knows to write HTML and CSS), there are still some common challenges that make me feel like travelling back in time before collaboration tools and concepts like staging, deployment, and git workflows became common practice.
I hope this article will help other developers not to waste their time and scratch their heads about WordPress a little less.
Top comments (1)
Updated the post adding a disclaimer so that people rather use a commercial tool for migrating large or complicated sites, unless, like me in this case, you have nothing but a small, manageable amount of data and configuration and nothing to lose on the target system.