Getting started

Migration moves a WordPress database and media library between two sites: push this site to another, pull another site into this one, or export and import a .sql.gz file. Themes and plugins are out of scope on purpose.

Install on both sites#

wp plugin install subset-migration --activate

Install it on both sites. On multisite, network-activate it.

Connect them#

On the site you will connect to, open

Tools → Subset Migration → Connection settings (placeholder — not final) and allow push, pull or both. Both are off by default, so a site nobody has configured cannot be overwritten. Copy that site’s connection info — its URL and a secret key — and paste it into Subset Migration on the other site.

Run a pull#

Choose Pull, pick what to bring across (the database, the media library or both) and read the preview: it lists the tables, the URL and path rewrites, and the size of the backup that will be taken first.

The job runs in resumable steps. If the browser closes or a request fails, resume it from the same screen, or with wp subset migration resume.

What stays behind#

A pull or import replaces the destination’s database, but these stay with the destination: its connection settings and saved connections, home, siteurl, upload_path, upload_url_path, blog_public, and the plugin’s own activation.

Because the users table is replaced too, you are signed back in as the user with the same username in the new data, or signed out if there is none.

What to read next#

The developer reference covers WP-CLI, the hooks fired around a migration, and locking settings from wp-config.php.