Skip to content

[00] Subset Sync, User guide

Getting started

Install Subset Sync on two sites, connect them, preview a pull and run it, and know what stays behind on the destination.

Subset Sync moves a WordPress database and media library between sites. You can push this site to another one, pull another site into this one, or export and import a .sql.gz file. This page takes you from install to your first pull.

The free plugin never moves themes or plugins. Subset Sync Pro adds that.

Install on both sites

You need Subset Sync on both sites. WordPress 6.0 and PHP 8.1 or newer are required.

  1. Download the free Subset Sync zip from subsetwp.com/download/sync.
  2. In wp-admin, go to Plugins → Add New → Upload Plugin, choose the zip and click Install Now.
  3. Activate it. On multisite, network-activate it.

The screen is at Subset → Migration, with the tabs Migrate, Backups, History and Connection. On multisite it’s at Network Admin → Subset → Migration.

Connect the sites

Both push and pull are off by default, so nobody can overwrite a site you haven’t set up.

  1. On the site you’ll connect to, open Subset → Migration → Connection.
  2. Under Other sites can, tick Pull from this site, Push to this site or both, then click Save changes.
  3. Click Show the URL and key and copy the connection info. Treat it like a password.
  4. On the other site, open the Migrate tab and paste it into Remote site connection info.

To pick the site from a list next time, click Preview and save instead of the plain preview button. You can also add it under Connection → Saved connections.

If you think a key has leaked, click Generate new key. Any site using the old connection info stops working until you give it the new info.

Run a pull

  1. On the Migrate tab, choose Pull.
  2. Pick a saved connection or paste the connection info.
  3. Under What to migrate, tick Database, Media library (uploads) or both. Media copies only new and changed files unless you choose All files.
  4. Click Preview pull.
  5. Check the preview, tick the box that confirms the database will be replaced, and start it.

Site URLs, http and https, and file paths are rewritten for you, including inside serialized and JSON data. Add your own pairs under Advanced options → Add find & replace.

The job runs in steps you can resume. If the browser closes or a request fails, click Resume on the Migrate tab or run wp subset sync resume.

Check the preview first

Every push and pull shows a preview before anything changes. It lists:

  • the direction, both sites’ URLs and whether either is marked as production
  • the tables that would be copied, with row counts and sizes, and any you left out
  • how many media files would be sent or deleted
  • every find & replace pair, with sample rewrites of the home option and a post
  • the estimated size of the backup taken first

Building the preview writes nothing on either site. On the command line, --dry-run prints the same preview and stops:

wp subset sync pull Staging --media --dry-run

To see how far two sites have drifted apart without migrating, run wp subset sync diff <remote>. It’s read-only on both sides.

Protect your production site

On a live site, open Connection and tick This is a production site. Replacing that site’s database by a push, pull, import or restore then asks you to type its domain first. Without the setting, a checkbox is enough.

The guard works on the command line too. You need --confirm-production=<domain>, and --yes alone isn’t enough. To refuse pushes to production entirely, untick Push to this site there as well.

Make it smaller

Under Advanced options → Leave out, you can skip transients, spam and trashed comments, post revisions and auto-drafts. You can also untick tables you don’t want to copy. Core tables such as options and users are always migrated.

On the command line, --lean skips spam, revisions and auto-drafts in one go, and --exclude-tables or --tables chooses tables.

What stays on the destination

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 and blog_public
  • Subset Sync’s own activation

The users table is replaced too. Afterwards, you’re signed in as the user with the same username in the new data. If there isn’t one, you’re signed out and need an account from the source site.

Subset Sync copies tables and their data. Views, triggers, stored routines and events aren’t copied.

Multisite

A network migrates as a whole by default, to or from another network of the same type. To move one subsite to or from a single site, choose it under Subsite on the Migrate tab, or pass --subsite=<id|url>. This is in the free plugin.

When a single site moves into a subsite, its users are merged into the network and matched by login. The subsite must already exist.

Moving between a subdomain network and a subdirectory network needs Subset Sync Pro.

Found a bug or want a feature? Open an issue at subset-feedback (opens in a new tab). For anything else, email hello@subsetwp.com.