How to Migrate Joomla 3 to Joomla 5 : Full Upgrade Path [2026]
You cannot jump straight from 3 to 5. Here is the real path, the extension casualties, and when rebuilding beats migrating.
You have a Joomla 3 site that still works, and you have been told it is end of life and needs to move to Joomla 5. Every guide you have found tells you to click Update, which is precisely the advice that will break the site — because you cannot upgrade Joomla 3 to Joomla 5 in one step, and the core upgrade is not the part that fails anyway.
The blocker is almost never Joomla. It is your extensions. This guide covers the real path — 3.10 to 4.x to 5.x — with the pre-flight work that determines whether the migration succeeds, and an honest decision table on when the answer is to rebuild instead.
The path, and why there is no shortcut
Joomla 4 was a rewrite. The 3.x codebase and the 4.x codebase share a name and very little else: the MVC structure changed, the template system changed, the namespace layout changed, and Joomla 3 extension code does not run on Joomla 4 without work.
Joomla 5, by contrast, is an evolution of 4 with deprecated code removed. The upgrade from 4 to 5 is genuinely straightforward.
Joomla 6 has been the current line since October 2025, and Joomla 5 remains supported alongside it — feature support to October 2026, security fixes to October 2027. Landing on 5.x is still the right target for this migration, because 5 is the bridge you have to cross anyway. Once you are there and stable, the step from 5 to 6 is a routine major upgrade; the main thing to check is PHP, since Joomla 6 requires 8.3 as a minimum and 8.4 is recommended.
| Step | From | To | Difficulty | What breaks |
|---|---|---|---|---|
| 1 | Joomla 3.x | Joomla 3.10.x | Trivial | Almost nothing — a normal minor update |
| 2 | Joomla 3.10 | Joomla 4.4 | Hard | Extensions, template, custom code, overrides |
| 3 | Joomla 4.4 | Joomla 5.x | Easy | Extensions using APIs removed in 5 |
Step 2 is the migration. Steps 1 and 3 are updates. Budget accordingly: on a typical small business site, steps 1 and 3 take under an hour between them, and step 2 takes anything from an afternoon to several days depending entirely on what is installed.
Joomla 3.10 reached end of security support in August 2023. It receives no patches of any kind. A Joomla 3 site on the public internet in 2026 is running unpatched software with publicly documented vulnerabilities in the ecosystem around it. This is not a reason to rush the migration and break the site — it is a reason to start it now rather than next quarter, and to consider whether the site should be behind a WAF in the meantime.
Pre-flight: the extension audit
Do this before anything else. It determines whether the migration is a two-hour job or a rebuild, and it is the only part of the process that cannot be automated.
List every extension and its current status
Go to System → Manage → Extensions and filter by type. Write down every non-core component, module, plugin, template and library, with its version and developer. Include things you think are unused — you will need to decide about them regardless.
Then, for each one, find out three things: does a Joomla 5 version exist; if so, is it a paid upgrade; and if not, is there a maintained alternative.
Sort the results into four buckets, because each demands different work:
| Bucket | Meaning | Action | Typical effort |
|---|---|---|---|
| Compatible | Developer ships a Joomla 5 version | Note the version, budget any upgrade fee | Minutes |
| Replaceable | Abandoned, but a maintained equivalent exists | Plan a data migration into the replacement | Hours to days per extension |
| Removable | Installed but unused or trivially replaced | Uninstall before migrating | Minutes |
| Blocking | Abandoned, no equivalent, holds critical data or function | Custom development, or reconsider the whole migration | Days to weeks |
The count in the Blocking column is your real decision input. One blocking extension usually means custom work. Three or more, and rebuilding often costs less than migrating.
An extension that claims Joomla 5 support but has had no release in two years and an unanswered support forum is a future blocking extension you have not identified yet. Look at release cadence and support responsiveness, not only the compatibility badge. You are choosing what to depend on for the next five years, and the Joomla 4 transition is exactly the event that ended a number of long-running extension projects.
Pre-flight: the Pre-Update Check
Joomla 3.10 shipped a tool specifically for this. It is in System → Joomla! Update, and it appears once you have set the update channel to Joomla 4.
Run it and read the whole list
Update to the latest Joomla 3.10 first — the tool only exists there. Then in System → Joomla! Update → Options, set the Update Channel to Joomla Next. Return to the main screen and a Pre-Update Check panel appears.
It reports your PHP and database versions against Joomla 4 requirements, and lists every installed extension with a compatibility status pulled from the Joomla Extensions Directory.
Treat the output as a strong hint rather than a verdict. It reads published compatibility data, which developers do not always keep current, so it produces both false alarms and false reassurance. An extension marked compatible can still break; one marked unknown may be fine. Your own audit is authoritative; the tool is there to make sure you did not miss anything.
It will also tell you if your PHP is too old. Joomla 4.4 needs PHP 7.2.5 minimum but you should be on 8.1 already, because that is what Joomla 5 will require in step 3.
Pre-flight: backup, and actually test it
Everyone takes a backup. Far fewer people confirm the backup restores, which is the only property of a backup that matters.
Take a full backup and restore it somewhere
Take a complete backup — files and database together, not one or the other. Then restore it to a subdomain or a local environment and load the site. Log in. Click through a few pages.
If the restore fails, you have discovered that now, with a working production site, rather than at midnight with a broken one. This is a genuinely common discovery: partial backups that omitted the database, archives truncated by a hosting size limit, backups of a directory that was not the web root.
A rollback plan answers a specific question: if this goes wrong at 3pm on a Tuesday, what exact sequence of commands returns the site to working order, and how long does it take? “We have backups” is not an answer to that question. Write the sequence down before you start, and know your restore time — because if it is four hours, you need a maintenance window, not a lunch break.
Staging first, always
Do not migrate production. Migrate a copy, fix everything, then either promote the copy or repeat the now-known-good sequence on production.
Build the staging copy
- Create a subdomain, e.g.
staging.example.com, with its own document root and database. - Restore your tested backup into it.
- Update
configuration.phpwith the new database credentials, and set$tmp_pathand$log_pathto paths that exist on the new location. - Set Global Configuration → Site → Robots to
noindex, nofollowand add arobots.txtdisallow. - Password-protect the subdomain at the web server if you can.
That fourth step is not optional. A staging site that gets indexed competes with production for its own content, and it will be discovered — crawlers find subdomains through certificate transparency logs whether or not anything links to them.
Step 1: Get to Joomla 3.10.x
On staging, run System → Joomla! Update and take the site to the latest 3.10 release. This is an ordinary minor update. If it fails, fix that before going further — a site that cannot complete a 3.x minor update will certainly not survive a major migration.
While you are here, do the housekeeping that makes the next step cleaner:
- Uninstall everything in the Removable bucket. Every extension you delete now is one you do not have to test after migrating.
- Empty the trash: articles, categories, menu items, modules.
- Clear all caches and truncate the session table.
- Note every template override you have, and which template they belong to. They will not carry over.
Step 2: The 3.10 to 4.4 upgrade
Switch the update channel and run it
In System → Joomla! Update → Options, set the Update Channel to Joomla Next. The main screen will now offer Joomla 4.4.
Before clicking, raise your PHP limits — max_execution_time to at least 300 and memory_limit to 256M. The upgrade rewrites a large number of files and a 30-second timeout mid-way leaves you with a half-upgraded installation, which is the worst state to be in.
Then run it and do not touch the browser tab until it finishes.
What you should expect on the other side: the administrator looks completely different, because Joomla 4 replaced the admin template. The front end may look broken or render as unstyled HTML, because your Joomla 3 template does not work on Joomla 4. Some extensions will be disabled. None of this means the upgrade failed.
Step 3: Deal with the casualties
This is the actual work, and it is why this cannot be a one-evening job on a complex site.
| Symptom | Cause | Fix |
|---|---|---|
| Front end unstyled or broken | Joomla 3 template incompatible | Install a Joomla 4/5 template — the vendor’s J4 version, or Cassiopeia while you decide |
| 500 error on a specific page | An extension calling a removed class | Update that extension; if none exists, disable and replace it |
| Extension missing from admin | Disabled during upgrade as incompatible | Install its Joomla 4 version over the top |
| Custom overrides doing nothing | Override paths belong to the old template | Recreate them in the new template’s html/ directory |
| Editor buttons missing | Editor plugins not migrated | Reinstall or replace the editor extension |
| Blank white page site-wide | Fatal PHP error, reporting off | Set Error Reporting to Maximum and read the message |
| Images missing in articles | Media paths changed by an old editor plugin | Search and replace paths in article content, carefully, from a backup |
Work in this order
- Get the front end rendering. Install a Joomla 4-compatible template. Do not evaluate anything else until the site displays.
- Restore administrator function. Disable every third-party plugin, then re-enable one at a time, checking the site after each. This isolates a fatal error in minutes rather than hours.
- Update every remaining extension to its Joomla 4 version.
- Rebuild overrides in the new template, from the current core files rather than by copying your Joomla 3 versions — the underlying layouts have changed.
- Test the things that generate value: forms submit and arrive, search returns results, logins work, any e-commerce or booking flow completes.
Joomla 4 changed core layout files substantially. A Joomla 3 override dropped into a Joomla 4 template will either error or silently render outdated markup missing accessibility and structural improvements. Re-fork each one from the current core file and re-apply your change. This is usually less work than it sounds, provided you documented what each override actually changed — and a strong argument for documenting them.
Step 4: The 4.4 to 5.x upgrade
Once the Joomla 4 site is genuinely working — not “mostly working” — this step is short.
Confirm PHP 8.1, then update
Joomla 5 requires PHP 8.1 minimum. Set the staging site’s PHP to 8.2 and confirm the site still works on Joomla 4 before updating, so that you are testing one change at a time.
Then run the Pre-Update Check again in System → Update → Joomla, resolve anything flagged, and run the update.
Joomla 5 removed code deprecated in 4. Extensions that worked on 4 while emitting deprecation notices may stop working on 5. Joomla 5 does ship a Behaviour plugin providing backward compatibility for some removed APIs — leave it enabled during migration, but treat it as a bridge, not a destination, and chase the affected extensions for proper updates.
Going live
Promote the staging site deliberately
- Announce a maintenance window and put production into Offline mode.
- Take a final production backup. Content added since you copied to staging lives only here.
- Reconcile that content — either freeze publishing during migration, or migrate the newer database again through the same now-proven sequence.
- Move staging files to the production document root and restore the staging database over production’s.
- Update
configuration.php: database credentials,$tmp_path,$log_path, and clear$live_siteif it was set for staging. - Set Robots back to
index, followand remove the stagingrobots.txtdisallow. - Take the site online and work through the checklist below.
Post-launch, verify in this order: homepage renders; a deep page renders (proves rewriting); administrator login works; a contact form submits and the email arrives; search returns results; the sitemap loads and is resubmitted; and Search Console reports no sudden crawl error spike over the following week.
When migrating is the wrong answer
Sometimes the honest recommendation is not to migrate. This table is the calculation, stated plainly.
| Situation | Migrate | Rebuild |
|---|---|---|
| Under 100 articles, stock extensions, standard template | Yes — likely a day’s work | Unnecessary |
| Large content archive, few extensions | Yes — the content is the value and it migrates cleanly | Wasteful |
| Heavy custom component holding core business data | Only with development budget | Consider — may be cheaper than porting |
| Three or more blocking abandoned extensions | Rarely worth it | Usually yes |
| Design is dated and due a redesign anyway | Only migrates a design you are discarding | Yes — combine the two projects |
| Site is small, seldom updated, mostly static | Possible | Consider a static site or a simpler CMS entirely |
| Nobody maintains the site and nobody will | Postpones the problem | Reduce it to something that needs no maintenance |
The last row is uncomfortable and worth stating. A great many Joomla 3 sites are brochure sites that changed twice in eight years. Migrating one to Joomla 5 buys a CMS that now needs patching every few weeks to host content that never changes. Exporting it to flat HTML, or moving it to a hosted site builder, is occasionally the professional answer even though it means one fewer Joomla site in the world.
Where you do migrate, note that content migrates far better than presentation. Articles, categories, users, menus and media come across reliably. Templates, overrides, custom modules and anything design-related will need rework regardless. Plan the project around that split.
Realistic time budget
| Phase | Simple site | Typical business site | Complex site |
|---|---|---|---|
| Extension audit | 1 hour | 3–4 hours | 1–2 days |
| Backup and staging setup | 1 hour | 2 hours | Half a day |
| 3.x to 3.10 | 15 min | 30 min | 1 hour |
| 3.10 to 4.4 and fixing casualties | 2–3 hours | 1–2 days | 1–3 weeks |
| Template and override rework | 1 hour | 1 day | 1–2 weeks |
| 4.4 to 5.x | 30 min | 1 hour | Half a day |
| Testing and go-live | 1 hour | Half a day | 2–3 days |
These are working estimates, not promises. The variance sits almost entirely in the extension and template rows, which is why the audit comes first: it is the only part that tells you which column you are in.
Frequently asked questions
Can I upgrade Joomla 3 straight to Joomla 5?
No. There is no direct path and no tool that provides one. You must go 3.10, then 4.x, then 5.x. Attempts to shortcut it — replacing files by hand, running the 5 installer over a 3 database — produce an unbootable site with a partially converted database.
Will my content survive the migration?
Yes, in normal cases. Articles, categories, users, menus, media and core settings migrate reliably. What does not survive is presentation: your template, your overrides, and any extension without a Joomla 4/5 version. Content is the durable asset; design and extensions are the rework.
How long does a Joomla 3 to 5 migration take?
Anywhere from an afternoon to several weeks, determined almost entirely by extensions. A stock site with a handful of common extensions is a day. A site with a custom component and an abandoned commercial template is a project with a budget. The extension audit is what tells you which you have, which is why it comes first.
What is the Pre-Update Check and can I trust it?
It is a tool in Joomla 3.10 and 4.x that checks PHP, database and installed extensions against the target version’s requirements, reading published compatibility data from the Joomla Extensions Directory. Trust it to catch things you missed; do not trust it as a verdict, because that data is only as current as developers keep it.
My Joomla 3 template has no Joomla 5 version. What now?
Three options: buy the vendor’s newer template if they have one and accept it will look different; rebuild the design on Cassiopeia or another Joomla 5 template; or treat it as the moment to do the redesign the site probably needed anyway. There is no way to run a Joomla 3 template on Joomla 5 — the template system changed fundamentally.
Is it safe to run Joomla 3 for a few more months?
Not really. Joomla 3.10 has had no security support since August 2023, so any vulnerability found since then is unpatched and stays that way. If you cannot migrate immediately, reduce the exposure: put the site behind a WAF, restrict administrator access by IP, remove unused extensions, and enforce two-factor authentication. Those are mitigations, not fixes.
Should I hire someone or do this myself?
Do the extension audit yourself regardless — it needs knowledge of the site that nobody else has, and it is the input to every other decision. If the audit shows stock extensions and a maintained template, the migration is well within reach of a competent administrator. If it shows a custom component or several abandoned dependencies, get a quote for both migrating and rebuilding before committing to either.