Developer · Guide
How to Migrate WordPress With WP-CLI

Short answer
To migrate WordPress with WP-CLI, export the database on the source site, copy the files to the new host, and import the database there. Then run wp search-replace with --dry-run first, run it for real with --skip-columns=guid, and set WP_HOME and WP_SITEURL in wp-config.php if needed. Finally, check the home page, dashboard, links, and widgets, and flush caches.
Key takeaways
- WP-CLI is a command line interface for WordPress, and WP-CLI 2.12.0 needs PHP 7.2.24 or later and WordPress 4.9 or later.
- Export the database with wp db export, copy the files, then import with wp db import on the new host.
- Run wp search-replace with --dry-run first, then run it for real with --skip-columns=guid.
- A plain search and replace can break serialization, so use wp search-replace instead of editing the SQL file.
- Set WP_HOME and WP_SITEURL in wp-config.php with https and no trailing slash when the new domain must take effect at once.
What is WP-CLI and when should you use it to migrate?
WP-CLI is a command line tool for WordPress, and it suits a migration when you have SSH access and want fast database and file steps.
Make WordPress CLI states that WP-CLI is a command line interface for WordPress (checked November 2026). You type commands in a terminal instead of clicking through the dashboard. That shape fits a migration because the main jobs are database export, database import, and URL replacement.
The current stable release is WP-CLI 2.12.0, published 7 May 2025. It needs PHP 7.2.24 or later and WordPress 4.9 or later (checked November 2026).
WP-CLI calls itself the command line for WordPress, and its project site shows the same database export and search-replace flow for moving a database between environments (checked November 2026).
Use WP-CLI when your host gives you SSH access and the site is large. A large database can time out in a browser-based import, while a command line import keeps running. Use it when you need to repeat the same steps on a staging copy first.
Do not use WP-CLI when you have no SSH access. In that case, use the manual method or a migration plugin instead. A guide on how to migrate WordPress manually covers the dashboard and FTP route in full.
What do you need before you start a WP-CLI migration?
You need SSH access, a backup of the source site, the new host login details, and the new domain name before you start.
Check SSH access first. Ask your host for the SSH host, port, username, and password or key.
Log in once and run wp --info to confirm WP-CLI is present. If the command is not found, install it with the steps in the next section.
Take a full backup before you touch the live site. A guide on how to back up a WordPress database covers the database part of that backup. Keep a copy of the files too, so you can restore the source site if a step fails.
Note the old and new URLs in full, with the same spelling. Write down the old domain, the new domain, and whether each one uses http or https. A small spelling slip in a URL can leave links pointing at the old site.
Check the new host for PHP and WordPress support. WP-CLI 2.12.0 needs PHP 7.2.24 or later and WordPress 4.9 or later (checked November 2026). Confirm the new site can run the same PHP version as the old site before you move files.
How do you install WP-CLI on your server?
Install WP-CLI by downloading the phar file, checking it, making it executable, and moving it into your path.
Make WordPress CLI gives the handbook install flow for WP-CLI (checked November 2026). Run these commands in order on the server where you want WP-CLI to work.
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
php wp-cli.phar --info
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
wp --info
The first command downloads the phar file. The second command checks that PHP can run it and shows the version.
The third command makes the file executable. The fourth command moves it to /usr/local/bin/wp so you can call it as wp from any folder.
Run wp --info last to confirm the install. It should show the WP-CLI version, the PHP version, and the WordPress version for the site in the current folder. If it shows an error, check that PHP is installed and that the file moved to the right place.
Some hosts already install WP-CLI for you. If wp --info works before you start, skip the install steps and move on. Managed hosts may also limit which folders you can write to, so check the host docs if sudo mv fails.
How do you export the database and copy the files?
Export the database on the source site with wp db export, then copy the WordPress files to the new host.
WordPress Developer Resources states that wp db export exports the database to a file or to STDOUT (checked November 2026). Run it from the WordPress root folder on the source site.
wp db export backup.sql
That command writes a file named backup.sql in the current folder. Keep that file with your backup. The same command page states that wp db dump is an alias-style export (checked November 2026).
Copy the files next. Copy the whole WordPress folder, including wp-content, wp-config.php, and the core files.
Use scp, rsync, or your host file manager to move them to the new host. Keep the folder layout the same on the new host.
Do not edit the SQL file by hand to change URLs. A plain search and replace across the whole database can break serialization, as the next sections explain. Export first, move the file as it is, and fix the URLs with wp search-replace after the import.
Check the file copy when it finishes. Confirm that wp-content/uploads moved in full and that wp-config.php is present on the new host. A missing uploads folder is a common cause of broken images after a move.
How do you import the database on the new site?
Import the database on the new site with wp db import, then check the database before you change any URLs.
WordPress Developer Resources states that wp db import imports a database from a file or from STDIN (checked November 2026). Run it from the WordPress root folder on the new site.
wp db import backup.sql
That command loads the SQL file into the database named in the new wp-config.php file. Update wp-config.php on the new host first, with the new database name, username, password, and host. If the import reports an error, check those four values before you try again.
Check the database after the import. WordPress Developer Resources states that wp db check checks the current database status (checked November 2026). Run wp db check and read the result for errors.
| Command | What it does | When to use it |
|---|---|---|
| wp db export | Exports the database to a file or to STDOUT | On the source site, before you move |
| wp db import | Imports a database from a file or from STDIN | On the new site, after you copy files |
| wp db dump | Alias-style export of the database | As an alternative to wp db export |
| wp db check | Checks the current database status | After an import, before URL changes |
| wp db clean | Removes all tables with the table prefix | Only when you need a clean start |
The same command page states that wp db clean removes all tables with the table prefix (checked November 2026). Do not run wp db clean on a live site unless you want to wipe its tables. It is a reset tool, not a routine migration step.
How do you update URLs with wp search-replace?
Update URLs with wp search-replace, run it with --dry-run first, then run it for real and skip the GUID column.
WordPress Developer Resources states that wp search-replace searches all rows in a selection of tables and replaces the first string with the second (checked November 2026). By default it uses tables registered to the $wpdb object. On multisite it covers only the current site tables unless you add --network.
Start with a dry run. WordPress Developer Resources states that --dry-run runs the whole operation and shows a report but does not save changes (checked November 2026). Run the dry run with your old and new URLs.
wp search-replace 'http://example.test' 'http://example.com' --skip-columns=guid --dry-run
Read the report. It shows how many replacements it would make in each table.
If the count looks wrong, check the spelling of the old URL and the new URL. Fix the spelling and run the dry run again.
Run the same command without --dry-run when the report looks right. The example above uses --skip-columns=guid to leave the GUID column alone. Moving WordPress states that you should never, ever, change the contents of the GUID column, under any circumstances (checked November 2026).
WordPress Developer Resources states that wp search-replace handles PHP serialized data in a smart way and does not change primary key values (checked November 2026).
That matters because a plain search and replace across the whole database can break serialization. Some themes and widgets store values with the length of the URL marked, and when the length changes, things break.
Use --regex only when you need a pattern match. WordPress Developer Resources states that --regex runs the search with a regular expression and takes about 15-20x longer (checked November 2026). A plain string match is faster for a normal domain change, so use it first.
How do you change the site URL in wp-config.php?
Set the site URL in wp-config.php with WP_HOME and WP_SITEURL when you need the new domain to take effect at once.
Add these two lines to wp-config.php on the new site, with your own domain in place of the example.
define('WP_HOME', 'https://example.com');
define('WP_SITEURL', 'https://example.com');
The WordPress Advanced Administration Handbook states that both settings should include the https part and should not have a trailing slash (checked November 2026). The source is WordPress Advanced Administration Handbook (checked November 2026).
Defining these values in wp-config.php overrides the database settings. The same handbook states that defining them greys out the fields in Settings then General (checked November 2026). That is normal, and it tells you the file values are in force.
Use this step when the database still holds the old URL or when you cannot reach the dashboard yet.
Remove the lines later if you want the dashboard fields to work again. Keep the values in the file while you test the new site, so the site does not flip back to the old domain.
How do you check the migrated site works?
Check the migrated site by visiting the home page, logging in, testing links, and flushing caches.
Open the new home page in a private browser window. Check the logo, menus, images, and footer.
Click through five or six pages and posts. If images are missing, check that wp-content/uploads copied in full.
Log in to the dashboard on the new domain. Open Settings then General and confirm the WordPress Address and Site Address show the new domain. If the fields are greyed out, the wp-config.php values are in force, as noted above.
Test the parts that store URLs in serialized data. Check widgets, menus, and theme settings, since those are the areas where a plain search and replace can break serialization.
The Moving WordPress warns that a plain search and replace across the whole database can break serialization because some themes and widgets store values with the length of the URL marked (checked November 2026).
Flush caches after the URL change. Clear the caching plugin cache, the host cache, and your browser cache.
Then reload the home page and check it again. A guide on fix broken links after migration covers the link checks to run next.
Test forms, search, and login as well. Submit a test form, run a site search, and log out and back in. If a form still posts to the old domain, run wp search-replace again for that URL form and check the dry run report first.
What mistakes should you avoid?
Avoid editing the SQL file by hand, changing the GUID column, and skipping the dry run.
Never edit the exported SQL file in a text editor to change URLs. Moving WordPress states that a plain search and replace across the whole database can break serialization because some themes and widgets store values with the length of the URL marked (checked November 2026).
Use wp search-replace instead, since it handles PHP serialized data in a smart way.
Never change the GUID column. Moving WordPress states that you should never, ever, change the contents of the GUID column, under any circumstances (checked November 2026). Use --skip-columns=guid in your wp search-replace command to keep that column safe.
Do not skip the --dry-run step.
The dry run shows the report before any change is saved, so you can catch a spelling slip in the old or new URL. A guide on how to set up a staging site for WordPress shows how to test the whole move on a copy first.
Do not run wp db clean by mistake. WordPress Developer Resources states that wp db clean removes all tables with the table prefix (checked November 2026). That wipes the site database, so only use it when you mean to start clean.
Do not use --regex for a plain domain change. WordPress Developer Resources states that --regex takes about 15-20x longer than a plain search (checked November 2026). Save it for pattern matches that a plain string cannot cover.
A plugin route can help when SSH is not an option. A guide on how to migrate WordPress with Duplicator covers one plugin route.
A guide on how to migrate with All-in-One WP Migration covers another plugin route.
Frequently asked questions
Do I need SSH access to use WP-CLI for a migration?
Yes. WP-CLI runs in a terminal on the server, so you need SSH access to run its commands. If your host does not give you SSH access, use the manual migration method or a migration plugin instead. Ask your host for the SSH host, port, username, and login details before you start.
What does wp search-replace do?
It searches all rows in a selection of tables and replaces the first string with the second, such as an old domain with a new domain. By default it uses tables registered to the WordPress database object, and on multisite it covers only the current site unless you add the network flag. It handles PHP serialized data and does not change primary key values.
Should I run wp search-replace with --dry-run first?
Yes. The dry run runs the whole operation and shows a report but does not save changes. Read the report to check how many replacements it would make in each table. If the count looks wrong, check the spelling of the old and new URLs, then run the dry run again before you run the command for real.
Can I change the GUID column during a migration?
No. Never change the contents of the GUID column, under any circumstances. Use the skip-columns option with the value guid in your search-replace command to leave that column alone. Changing GUID values can break feeds and post identity, so keep that column out of every URL replacement you run.
How do I change the site URL after moving WordPress?
Add WP_HOME and WP_SITEURL lines to wp-config.php on the new site, with the new domain in both. Both settings should include the https part and should not have a trailing slash. Defining them in wp-config.php overrides the database settings and greys out the fields in Settings and General, which is normal while the file values are in force.
What does wp db clean do?
It removes all tables with the table prefix. Do not run it on a live site unless you want to wipe its tables, since it is a reset tool rather than a routine migration step. Use wp db check after an import to check the current database status instead, and only use wp db clean when you mean to start clean.
Sources
- Quick Start Make WordPress CLI
- wp search-replace WordPress Developer Resources
- wp db WordPress Developer Resources
- Migrating WordPress WordPress Developer Resources
- WP-CLI WP-CLI
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.


