A client of mine had been running a 50-page site on Joomla 3.10 for years. With Joomla 3 reaching end of life, the migration to Joomla 5 became unavoidable. I gave myself three days to do it. It took three days. Several things almost went sideways. Here's the actual diary.
Day 0 — The audit
Before any migration, you audit the existing site. What extensions are installed? What template is in use? What custom code has been added? Joomla 3 sites accumulate cruft over the years; you do not want to find out about it during the migration.
The audit revealed:
- 14 third-party extensions, of which 4 had no Joomla 4+ version
- A custom template with hardcoded Joomla 3 path references
- One core file modification someone had made years ago and forgotten
- A K2 component handling all of the news section's content
The K2 finding was the one that determined the migration strategy. K2 has no clean Joomla 5 path. Either I migrated K2 content into native Joomla articles, or I stayed on Joomla 3 forever. I picked option A.
Day 1 — Staging environment + K2 to native articles
Set up a staging environment first. Always. Migration on production is a recipe for the kind of phone call you don't want to receive.
The K2 to native article migration took most of day 1. There's no perfect tool for this — I used a SQL export from K2's tables, transformed the data, and imported into the standard Joomla content tables. Six hours of work, mostly because of edge cases (articles with custom field values, attached images stored in K2's own media handling).
By end of day 1, the staging site had all K2 content as native articles, but it was still on Joomla 3.
Day 2 — Joomla 3 → 4 → 5
You cannot migrate directly from Joomla 3 to Joomla 5. You go through 4.x as an intermediate. This is by design — Joomla 4 introduced the new architecture; Joomla 5 polishes it.
The 3 → 4 step is the dangerous one. Most things break here. Old templates are incompatible. Many extensions need replacement, not upgrade. The migration tool ("Joomla! Update") tells you what will break before it breaks; read its output carefully.
What broke for me on the 3 → 4 jump:
- The custom template — completely incompatible. Built a fresh Helix Ultimate-based template instead.
- 4 of the 14 third-party extensions — uninstalled and replaced with alternatives.
- The forgotten core file modification — this is the near-disaster. The modified file no longer existed in Joomla 4. The functionality the modification provided was now built-in.
Once at Joomla 4.4 stable, the 4 → 5 jump was uneventful. About 20 minutes total.
Day 3 — Cutover and the surprise
The plan: take production offline at 9pm, sync the staging database to production, swap directories, bring it back up by 11pm.
The execution: production went offline at 9pm. The database sync ran into a charset mismatch I hadn't caught — the production database was utf8, the Joomla 5 staging was utf8mb4. Conversion took an hour. By 11pm I was still at 80%.
The site was back online at 12:30am. With one bug: the language switcher (multi-language site) wasn't resolving correctly. Found and fixed at 1:15am. Final test pass complete at 1:45.
If I were doing it again, I'd catch the charset issue in advance. The "I should test the database sync separately" lesson has been written before. I'll likely write it again.
What I'd do differently
- Test the database sync before cutover day. Migrate a snapshot of the production database to staging weeks ahead. The charset issue would have shown up then.
- Plan the K2 migration as a separate project. Treating it as "part of the Joomla migration" compresses what should be its own dedicated work.
- Build the staging environment a week earlier. Three days of staging work felt rushed. Two weeks would have been comfortable.
- Schedule cutover for Friday night, not Tuesday. If something breaks, you have the weekend to fix it without business pressure.
The line items I underestimated
- Auditing third-party extensions (4 hours, not 1)
- K2-to-native conversion (6 hours, not 3)
- Template rebuild (full day, not half)
- Final testing (3 hours, not 1)
If you're budgeting for a similar migration, double whatever the migration's "official" instructions suggest. They're written for clean sites that don't exist outside of demo environments.
What I'd do exactly the same
Set up staging. Migrate K2 to native first. Walk through 4 as a deliberate stopping point before pushing to 5. Cutover late at night, not during business hours. Schedule a follow-up session 48 hours later to address whatever problems surface that the initial test missed.
The site has been on Joomla 5 for four months at the time of writing. Stable. Faster than the Joomla 3 version. Maintenance has been minimal. The migration was worth doing — but I would have been wise to schedule four days, not three.
