How to Plan a Joomla Major-Version Upgrade

Inventory the existing site

Record the Joomla version, PHP version, database environment, installed extensions, template, overrides, custom plugins, scheduled jobs and external integrations before changing anything.

The inventory should distinguish between components that are essential to the business and extensions that can be removed. That makes compatibility work easier to prioritize.

Confirm the supported upgrade path

Before scheduling the project, verify the currently supported migration path in Joomla’s official documentation. Major-version work should be planned around the specific source and target versions instead of assuming every installation can jump directly to the latest release.

Audit extensions and template compatibility

Create a compatibility matrix for third-party extensions and the active template. For each dependency, record whether a compatible release exists, whether a replacement is required, and whether custom code depends on APIs that changed between versions.

Custom overrides deserve separate review because they can continue to render while quietly depending on outdated markup or framework behavior.

Build a recoverable staging copy

Perform the upgrade on a staging environment that accurately represents production. Confirm that the backup can be restored before the upgrade starts; a backup that has never been tested is not yet a rollback plan.

Define acceptance tests

The test list should cover more than the home page. Include authentication, forms, search, menus, multilingual behavior, ecommerce or membership flows, email delivery, scheduled jobs, integrations and administrator workflows that the organization depends on.

Plan the production window and rollback

Document the deployment sequence, expected maintenance window, who can approve rollback, and what data may change during the window. Sites with orders, form submissions or member activity need a plan for data created between the staging copy and final production cutover.

Review again after launch

After production migration, monitor logs and business-critical workflows, remove obsolete compatibility layers when appropriate, and update the technical inventory so the next maintenance cycle starts with accurate information.