Migrate WordPress to a New Server: All-in-One WP Migration or WP-CLI

This article is a localized edition of the Japanese original. Read the Japanese original

A WordPress site consists of files (WordPress core, the themes, plugins and uploaded images in wp-content, wp-config.php and .htaccess) and a database (posts, settings, users and so on). Migrating to another server means moving both to the new server, setting the new database connection details, and finally switching DNS. If the domain changes, you also replace the URLs stored in the database.

This article explains how to migrate with a plugin and how to do it by hand with WP-CLI. Commands are for Ubuntu/Debian (on RHEL-based systems, the web server user name and some other details differ).

Migration overview

1. Check the source and destination environments and lower the DNS TTL in advance
2. Export the files and database on the source
3. Import them on the destination and set the connection details
4. Use the hosts file on your own PC to check the destination before switching DNS
5. Switch DNS and set up the SSL certificate
6. Shut down the old server after traffic to it stops

Step 1: Prepare for the migration

Check the environment

Check the following on the source and make sure the destination meets the same or newer versions. If the PHP version changes, also confirm that your themes and plugins support the new PHP.

cd /var/www/html          # The directory where WordPress lives
wp core version
wp eval 'echo PHP_VERSION, PHP_EOL;'
wp db query 'SELECT VERSION();'
wp db size --human-readable
du -sh wp-content/uploads
wp plugin list

wp eval shows the PHP version used by WP-CLI. It can differ from the PHP the web server uses, so also check under "Tools" → "Site Health" → "Info" in the admin.

Lower the DNS TTL

After you switch DNS, the old IP address stays cached in DNS servers around the world for the TTL (how long it may be cached). Before migrating, lower the TTL of the website's A record to around 300 seconds (5 minutes). The lowered value takes as long as the old TTL to spread, so if the old TTL is one day, lower it at least a day ahead.

# Check the current TTL (the number in the second column)
dig example.com A +noall +answer

Pause updates during the migration

Any posts, comments or orders made on the old server between the export and the DNS switch won't make it to the new server. Decide on a time window and hold off on updates during it. On sites that accept comments or orders, it's a good idea to announce the migration window in advance.

Method A: Migrate with All-in-One WP Migration

This plugin packs files and the database into a single .wpress file and imports it on the destination. It suits small sites and cases where SSH isn't available.

1. Install the plugin on the source, choose File as the destination under "All-in-One WP Migration" → "Export", and download the .wpress file.
2. Install a fresh WordPress on the destination and add the same plugin.
3. On the destination, open "All-in-One WP Migration" → "Import" and upload the .wpress file.

Notes:

• The maximum file size you can import is set by the server's upload limit and is shown on the import screen. If your file exceeds it, raise the server's PHP settings (such as upload_max_filesize), use the paid Unlimited Extension, or migrate with Method B.
• Importing replaces the destination's database and files with the exported site. Users are replaced too, so after importing, log in with the source site's username and password.
• After importing, open "Settings" → "Permalinks" and click "Save Changes" to rebuild the permalink settings.

Method B: Migrate by hand with WP-CLI and tar

If SSH and WP-CLI are available, this method is reliable even for large sites. For WP-CLI usage, see also WP-CLI database commands.

On the source server

cd /var/www/html

# Export the database
wp db export /tmp/site.sql

# Archive the whole WordPress directory (.htaccess and wp-config.php included)
# Put --exclude before the target (the final ".")
tar -czf /tmp/site-files.tar.gz -C /var/www/html \
  --exclude=./wp-content/cache \
  .

# Send to the destination
scp /tmp/site.sql /tmp/site-files.tar.gz user@new-server:/tmp/

The cache directory is excluded because it is rebuilt on the destination. If a backup plugin stores backups inside wp-content, excluding that directory too speeds up the transfer.

The exported files contain your database contents and passwords. Delete them from /tmp on the source once the transfer is done.

On the destination server

First, create the database and user (example for MySQL 8.0/MariaDB).

sudo mysql

CREATE DATABASE wp_new CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'wp_new_user'@'localhost' IDENTIFIED BY 'a-long-hard-to-guess-password';
GRANT ALL PRIVILEGES ON wp_new.* TO 'wp_new_user'@'localhost';
FLUSH PRIVILEGES;

Next, extract the files, update the connection details, and import the database.

sudo mkdir -p /var/www/html
sudo tar -xzf /tmp/site-files.tar.gz -C /var/www/html
sudo chown -R www-data:www-data /var/www/html
cd /var/www/html

# Change the connection settings in wp-config.php to the destination values
sudo -u www-data wp config set DB_NAME wp_new
sudo -u www-data wp config set DB_USER wp_new_user
sudo -u www-data wp config set DB_PASSWORD 'a-long-hard-to-guess-password'
sudo -u www-data wp config set DB_HOST localhost

# Import the database
sudo -u www-data wp db import /tmp/site.sql

# Check the site URLs
sudo -u www-data wp option get home
sudo -u www-data wp option get siteurl

wp db import imports the tables with the source's table prefix ($table_prefix). Because wp-config.php came from the source, the prefix matches as is. Delete the SQL file in /tmp once the import is done.

A common choice for permissions is 755 for directories and 644 for files. Restrict wp-config.php further, for example to 640, after confirming the web server user can read it.

sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;
sudo chmod 640 /var/www/html/wp-config.php

Create the web server configuration (Apache VirtualHost or Nginx server block) based on the source. Nginx does not use .htaccess, so you need to write try_files and other permalink settings in the server block.

If the domain changes: replace the URLs

If you keep the same domain and only change servers, you don't need this step.

If the domain changes, replace the URLs in the database in bulk. wp search-replace replaces values without breaking data that WordPress or plugins have serialized (stored in PHP's format). First check the count with --dry-run, take a database backup, and then run it.

# Check how many values would change (the database is not modified)
sudo -u www-data wp search-replace 'https://old-example.com' 'https://new-example.com' \
  --skip-columns=guid --dry-run

# If it looks right, run it
sudo -u www-data wp search-replace 'https://old-example.com' 'https://new-example.com' \
  --skip-columns=guid --report-changed-only

• The guid column identifies posts, and RSS readers and similar tools use it to detect duplicates. Don't rewrite it even when the URL changes (the official WP-CLI example also uses --skip-columns=guid).
• If old URLs starting with http:// remain, replace http://old-example.com the same way.
• To include plugin tables that WordPress doesn't register, add --all-tables-with-prefix.

After replacing, redirect requests for the old domain to the new domain with a 301. Here is an example .htaccess for the server that receives the old domain (it uses Apache's mod_rewrite).

RewriteEngine On
RewriteCond %{HTTP_HOST} ^(www\.)?old-example\.com$ [NC]
RewriteRule ^(.*)$ https://new-example.com/$1 [R=301,L]

If you use Google Search Console, add a property for the new domain and report the move with the Change of Address tool.

Step 2: Check with the hosts file before switching DNS

Before switching DNS, make only your own PC see the destination server. Add one line with the destination IP address and the domain to your PC's hosts file (not the server's /etc/hosts).

203.0.113.50  example.com www.example.com

203.0.113.50 is an example destination IP address. Find the destination IP by running ip -4 addr on the destination server or in your hosting company's control panel.

In the browser, check the front page, individual posts, images, logging in to the admin, contact forms and so on. If the destination doesn't have an SSL certificate yet, opening it over HTTPS shows a certificate warning. When you're done, remove the line from the hosts file.

Step 3: Switch DNS and set up the SSL certificate

In your DNS control panel, change the A records (example.com and www, plus AAAA records if you use IPv6) to the destination IP address, and check that the change has taken effect.

dig +short example.com A
dig +short example.com A @8.8.8.8

Get the Let's Encrypt certificate after the domain points to the destination (HTTP-01 validation checks by accessing the domain). Example for Nginx:

sudo certbot --nginx -d example.com -d www.example.com

For Apache, change --nginx to --apache. For details, see Setting up SSL on Nginx with Certbot. If you need a certificate before switching DNS, obtain it with the DNS-01 method or temporarily use the source's certificate.

Step 4: Check after the migration

cd /var/www/html
sudo -u www-data wp core verify-checksums
sudo -u www-data wp plugin status
sudo -u www-data wp cache flush
curl -sI https://example.com/ | head -1

• Permalinks: if post pages return 404, click "Save Changes" under "Settings" → "Permalinks" in the admin. Also check that mod_rewrite is enabled in Apache and that the VirtualHost allows AllowOverride (Fixing 404 errors after a migration). For WP-CLI's wp rewrite flush --hard to rewrite .htaccess, you need to list mod_rewrite under apache_modules in wp-cli.yml.
• Email: check that the destination server can send email, using a contact form or a password reset.
• WP-Cron: check that scheduled posts and recurring tasks run. If the source called wp-cron.php from the server's cron, set up the same on the destination.
• Cache: clear the caches of your caching plugin and CDN.

Step 5: Shut down the old server

Even after switching DNS, traffic keeps reaching the old server for the duration of the TTL. Watch the old server's access log and shut it down only after visitor traffic has stopped.

# On the old server, watch recent access (Nginx example)
sudo tail -f /var/log/nginx/access.log

Before canceling the old server, keep the latest backup (files and database) on hand.

Summary

• You migrate two things: files and the database. Lower the DNS TTL in advance.
• For small sites, All-in-One WP Migration works; if SSH is available, moving everything with wp db export and tar is reliable.
• Only when the domain changes, check wp search-replace with --dry-run before running it, and don't rewrite guid.
• Before switching DNS, check the destination through your PC's hosts file. Get the certificate after the switch.
• Shut down the old server after confirming traffic to it has stopped.

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)