Available for projects & agency overflow · Quick reply, from the person who does the work

Send a message contact@allaux.fr
FR EN TR
allaux.
Emergency Discuss my project

Migrating a WordPress multisite network

A WordPress multisite network hosts several subsites from a single installation. Migrating this kind of network adds a constraint a simple site doesn’t have: each subsite has its own content structure, and a global URL replacement breaks more than it fixes.

Describe my issue Send a message

What a multisite network adds compared to a simple site

A multisite network relies on a MULTISITE constant enabled in wp-config.php, and on a table that lists every subsite in the network with its associated domain or subdomain. Each subsite has its own content tables, prefixed with its own numeric identifier, but the whole network shares one common network-level user table: a user account created on the network can access several subsites without being duplicated.

Plugins add a further distinction to check before migrating: a plugin can be “network activated”, in which case it automatically applies to every subsite including ones created afterwards, or activated individually on a single subsite. This distinction doesn’t show up in the plugin’s own files, only in the network’s activation settings, which is why a prior inventory matters — otherwise a subsite can turn up missing a feature only after the switch.

This setup is stable and has been documented for a long time, but it directly changes how a migration has to run: there isn’t one content database to handle, but as many content structures as there are subsites, linked together by the network’s domain mapping table.

What a multisite migration adds

  • A network domain and subdomain mapping table to update, in addition to the content tables
  • A URL replacement that must run subsite by subsite, since wp search-replace’s --url option targets one specific subsite, not the whole network at once
  • Subsites that may have different active themes or plugins from one to another, to check individually
  • A network primary domain whose switch affects access to every subsite, not just one isolated site

How I run a multisite migration

  1. Subsite inventory

    I list every subsite in the network, its current domain or subdomain, and its own plugins or themes, noting which ones are network-activated rather than activated individually.

  2. Full copy to a test environment

    The files and database for the whole network are duplicated to a test environment before any URL change.

  3. URL replacement subsite by subsite

    I run wp search-replace with the --url option targeting each subsite individually, rather than a global replacement across the whole network.

  4. Checking each subsite

    I check that each subsite responds correctly with its new URL, that its settings and menus display normally, before moving to the next one.

  5. Switching the primary domain

    The network’s primary domain is only switched once every subsite has been individually checked, never before.

Related reading

Describe your need in one minute

A few targeted questions so I can reply with an estimate rather than another questionnaire.

origine
catalogue
extensions-premium (facultatif)
conserver (facultatif)
Please provide an email or a phone number so I can get back to you.

Please provide an email or a phone number so I can get back to you.

Frequently asked questions

Why can’t I just run wp search-replace once for the whole network?
Each subsite has its own content tables, prefixed with its own identifier. The --url option of wp search-replace targets one specific subsite: a global replacement risks mishandling some subsites.
Are user accounts duplicated across subsites?
No, the user table is shared across the whole network. An account created at network level can access several subsites without being recreated for each one.
What happens if I switch the primary domain before checking every subsite?
That’s the point of no return for this kind of migration: the whole network becomes unstable at once, not just one isolated subsite. I systematically check every subsite before this step.
Can one subsite have a different theme from the others?
Yes, each subsite can activate its own theme and plugins. I check each subsite individually during migration, since their configuration isn’t necessarily identical.
Does the PHP serialisation mechanism also apply to multisite?
Yes, exactly the same way as on a simple site, but repeated for each subsite. The full detail is explained on the page dedicated to zero-downtime host migration.

Related pages