WordPress major version upgrades (5.x → 6.x, and eventually 6.x → 7.x) are a different animal from minor releases. Minor releases (like 6.4.1 → 6.4.2) are mostly bug fixes with low compatibility risk. Majors land API deprecations, raised PHP minimum requirements, and core block replacements all at once — and those things hit operations hard.
The “just hit Update in the admin and patch whatever breaks” workflow can survive on a single personal site, but it tends to fall apart under multi-site maintenance — simultaneous failures across sites overwhelm root-cause triage. This post collects the things worth verifying before you run a major upgrade, as a seven-item checklist.
1. Has the minimum PHP version been raised?
Major WordPress releases sometimes raise the minimum supported PHP version (6.6 lifted it to PHP 7.2.24, and a future 7.0 will very likely require PHP 8.x). What matters operationally isn’t just the server’s PHP version and WordPress’s stated minimum — it’s the intersection with the PHP versions your plugins and themes actually run on.
You can usually upgrade your server’s PHP, but older themes and plugins not running on new PHP isn’t rare. A subtle failure mode here: traps like PHP 8.2+ deprecated warnings leaking into older WP-CLI JSON output, where nothing visibly errors but your operational tooling silently breaks. Before upgrading, run wp plugin list --format=json on the production PHP environment and verify you’re getting clean JSON. That one check catches a lot of post-upgrade pain.
2. Audit “Tested up to” for every plugin
Each plugin’s readme.txt carries a Tested up to: X.X line — the developer’s declaration of the highest WordPress version they’ve actually tested against. It’s the first signal for major-upgrade compatibility audits.
WP-CLI gives you the inventory in one shot:
wp plugin list --fields=name,version,update_version,update --format=table
Plugins where “Tested up to” is old AND no updates in the last year deserve scrutiny. Active development may have stopped, which means no fix is coming when the major upgrade breaks them. Better to identify replacement candidates pre-upgrade than to scramble post-upgrade.
3. Theme compatibility — child themes and deep customizations
Themes feel the major upgrade too. Watch especially for:
- Block editor APIs (5.x→6.x landed massive API changes here)
- Customized child themes (parent theme updates, but child theme hooks stay on the old API)
- Page-builder plugins and their version requirements
In client work, “the theme is too old to upgrade PHP” is a regular blocker. Theme-side constraints that effectively pin WordPress to an older version need to surface at planning time, not after you’ve already started the upgrade.
4. Database backups — keep at least three generations
Major upgrades often involve database migrations. WordPress migrations are idempotent in principle, but recovering from one that dies halfway is unpleasant. Take a full backup before running the upgrade, and keep the latest, one before, and one further back — three generations is the safe floor.
# DB export (compressed)
wp db export - | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
# wp-content if you want the full bundle
tar czf wp-content_$(date +%Y%m%d_%H%M%S).tar.gz wp-content/
For large sites, an SSH disconnect mid-export can leave a partial .sql lying around. Verify completion before moving on.
5. Run it in staging first
Hitting production with a major upgrade — even on a single site — is something to avoid. Mirror production into staging, upgrade there first, eyeball the front end, click through the admin, check WP-CLI, walk through the top plugins’ admin screens. Then production.
Some hosts ship a staging feature out of the box; that’s usually the fastest path. Otherwise an rsync to a separate directory on the same server (with a separate DB import) does the job.
The minimum verification list for staging:
- Admin opens; post editor renders correctly
- Critical front-end pages render normally
- Forms and other dynamic features actually work
wp plugin listreturns clean output
6. Use WP-CLI to stage the updates (skip the admin’s one-click)
The admin’s “Update” button is designed to fire everything at once. Core, plugins, themes — all in a batch. When something breaks, you can’t tell which one broke it. That’s particularly damaging on major upgrades.
WP-CLI lets you do core / plugins / themes separately, in order:
# 1. Core first
wp core update --version=6.7
# 2. DB migration
wp core update-db
# 3. Plugins one at a time
wp plugin update <plugin-name>
# 4. Themes the same way
wp theme update <theme-name>
Passing --version= keeps you from jumping multiple versions at once. From 6.4 to 6.7, going 6.5 → 6.6 → 6.7 instead of a direct jump makes it much easier to localize whatever goes wrong to a specific step.
A related gotcha: there are scenarios where WP-CLI itself fails to bootstrap because of a broken plugin. Knowing the --skip-plugins --skip-themes rescue flags pays for itself the first time WP-CLI refuses to start after an upgrade.
7. Write the rollback procedure down — before you upgrade
Last item: write down how you’ll roll back before you start. “I’ll just google it if I need to” doesn’t survive contact with reality — under outage stress you don’t want to be researching, you want to be executing a known procedure.
Minimum contents:
- DB restore command (using the backup from step 5)
- Filesystem restore command (the exact
tar xzf) - WP-CLI command to roll core back one version:
bash
wp core update --version=6.6 --force - Per-plugin rollback (the approach from pinpoint rollback with WP-CLI):
bash
wp plugin install <plugin-name> --version=X.X.X --force
The act of writing this down surfaces missing prep — you’ll find a missing backup, a server where WP-CLI isn’t installed, the wrong privileges. The document itself doubles as a pre-flight check.
Closing — ten minutes before saves hours after
Listing seven items makes the upfront work look heavy, but with practice the pre-upgrade check takes 10–15 minutes total. Charging in without it and recovering from a broken site is a multi-hour to half-day project. With more than a handful of sites under maintenance, that ratio dominates your operational economics.
“Just patch whatever breaks” works for a hobby site. It doesn’t work as a maintenance offering. Keep one checklist by your side, walk down it every time a major upgrade comes around — that alone bends the incident rate down measurably.