Joomla 3 reached end-of-life in August 2023. If you are still running it, you are running unpatched software. The migration path to Joomla 5 exists, but it is not the click-and-upgrade process many people expect — and the failures we see are almost always the same.
The first thing to understand: there is no direct J3 → J5 path
Joomla's upgrade system is incremental. You can upgrade J3 to J4, and J4 to J5. You cannot skip J4. This means a Joomla 3 migration to Joomla 5 is actually two upgrades, or a fresh installation with content migration — both of which have their own complexity.
Most projects we take over that went wrong skipped the audit phase, attempted the J4 upgrade, and discovered that half their extensions do not work on J4 — let alone J5. The upgrade completed, the site appeared functional, and then they found broken features over the next few weeks.
The audit phase — what you must do before touching anything
Before running any upgrade, every installed extension must be audited:
- Does a J4/J5-compatible version exist? When was it last updated?
- Is the extension still actively maintained? Has the developer abandoned it?
- If no compatible version exists: can you replace it with a different extension? Does it need to be custom-built?
- Are there custom components that need to be rewritten?
This audit typically takes 1–2 days on a mid-complexity J3 site. It is not optional. Every migration that skips this step ends up doing it retroactively — under time pressure, with a broken live site.
The template problem
Joomla 3 templates do not work on Joomla 4 or 5. The Bootstrap version changed (J3 used Bootstrap 2/3, J5 uses Bootstrap 5), the template override system changed, and the HTML output structure changed.
Your options:
- Purchase a new template — if your current template has a J5 version from its vendor, this is the fastest path
- Rebuild the template — if your template is heavily customised or the vendor has not updated it, rebuilding is the right choice
- Use Cassiopeia (J5 default) with overrides — for simpler sites, Joomla 5's default template with custom overrides is a cost-effective option
The most expensive mistake: Trying to "port" a J3 template by find-replacing Bootstrap class names. J5's template engine is different enough that this produces a site that looks approximately correct but breaks in unpredictable ways across browsers and screen sizes. Always rebuild.
Custom component rewrites
Joomla 4 introduced significant changes to the component architecture — updated MVC pattern, web services API, improved ACL integration. J3 custom components built with the old architecture do not work on J4+ without modification.
A custom J3 component rewrite for J5 involves:
- Updating the component manifest to J5 format
- Rewriting controllers to extend the J4/J5 base controller
- Updating models to use J4/J5's database API
- Rebuilding views using Bootstrap 5 compatible HTML and J5 layout system
- Updating install/uninstall scripts
- Adding web services API endpoints if the component needs REST access
For a moderately complex component (5–10 views, database tables, admin panel), expect 3–6 weeks of development. For simple components (1–2 views), 1–2 weeks.
Data migration and the J3 → J4 upgrade path
When the extension audit is complete and the template decision is made, the actual migration sequence is:
- Create a complete backup — files and database, tested restore
- Upgrade J3 → J4 on a staging clone (never on production first)
- Fix all extension and template issues on staging
- Verify all content, forms, and workflows
- Upgrade J4 → J5 on staging
- Verify again on J5
- Execute on production during a low-traffic window
Steps 2–6 on staging are not optional. We have never done a J3 → J5 migration that had zero issues on the first staging run. The issues found on staging are the issues that would have hit production.
When a fresh install is better than upgrading
For sites where J3 has accumulated significant technical debt — incompatible extensions, a heavily modified core, or a template nobody can trace the source of — a fresh J5 installation with content migration is sometimes faster and more reliable than the upgrade path.
This involves installing J5 fresh, migrating articles, categories, menus, and users via migration tools or custom scripts, rebuilding the template and components natively in J5, and going live on the new installation. The old J3 site remains untouched and can be compared against at any point.
Fresh installs produce cleaner results: No residue from J3 plugin tables that J5 does not understand. No legacy database schema quirks. No confusion about whether a bug is from the migration or pre-existing. When the codebase is messy, start clean.
Timeline expectations
- Simple J3 site, no custom components, compatible extensions: 2–4 weeks
- Mid-complexity J3 site, 1–3 custom components: 6–10 weeks
- Complex J3 site, 4+ custom components, custom template: 12–20 weeks
Running Joomla 3 and need to migrate?
20+ years on Joomla. We have done J3 → J5 migrations on sites with full custom component suites. Tell us what you have.
Get a Migration Assessment