Joomla 4 vs Joomla 5 — Key Differences and Migration Guide

In this tutorial, you'll learn the key differences between Joomla 4 and Joomla 5, including new features, removed components, system requirements, and how to migrate from Joomla 3.x through 4.x to Joomla 5.x safely.

What You'll Learn

• Major changes in Joomla 5 (WebAuthn, PHP 8.1+, MooTools removal, improved accessibility)
• Key features introduced in Joomla 4 (Bootstrap 5, no jQuery, workflow, task scheduler)
• What was removed or deprecated in Joomla 4 (Legacy plugins, Media Manager rewrite, Search component)
• Step-by-step migration from Joomla 3.x to 4.x
• Step-by-step migration from Joomla 4.x to 5.x
• Pre-upgrade checklist and post-upgrade tasks

Why It Matters

Joomla evolves with the web. Each major version brings modern PHP features, security improvements, and better performance. Joomla 3.x reached end of life in August 2023 — sites still on Joomla 3 are vulnerable to unpatched security issues. Joomla 4 introduced a modern foundation (Symfony, Bootstrap 5, no jQuery). Joomla 5 continues the modernization with stricter PHP requirements and removal of legacy code. If you manage a Joomla site, understanding these differences is essential for planning upgrades and keeping your site secure.

Real-World Use

A nonprofit organization ran their membership site on Joomla 3.10 for years. Hosting providers started requiring PHP 8.0+, but Joomla 3.10 only supports PHP 7.x. The site could not be updated. Security warnings appeared. After migrating to Joomla 4.x and then to Joomla 5.x, the site runs on PHP 8.2 with Redis caching, the Cassiopeia template loads 60% faster than the old Protostar template, and the new Workflow component lets staff manage article approvals without a third-party extension. The migration took two weekends and gave the site five more years of security updates.

Learning Path

flowchart LR
  A["Multilingual Sites"] --> B["Joomla 4 vs 5"]
  B --> C["Backups"]
  C --> D["User Groups"]
  D --> E["Custom Fields"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px
  class B current

Joomla Versions History

Understanding the version history helps you plan your migration path:

If you start a new project today, use Joomla 5.x. If you maintain an existing Joomla 3.x site, migrate to 5.x as soon as possible.

Joomla 5 Key Changes

Joomla 5 was released in October 2023. Here are the most important changes:

Removed MooTools Dependency

Joomla 3 relied heavily on MooTools, an old JavaScript library. Joomla 4 reduced MooTools usage. Joomla 5 removed it entirely. Any extension or template that depends on MooTools will break in Joomla 5.

WebAuthn Authentication

Joomla 5 introduces WebAuthn (Web Authentication) support. Users can log in using biometric authentication (fingerprint, face recognition) or hardware security keys (YubiKey) instead of passwords. This is a major security improvement.

New Privacy Tools

Enhanced privacy tools for GDPR compliance, including better cookie consent handling and data export/delete workflows.

Improved Accessibility

Joomla 5 meets WCAG 2.1 AA standards more comprehensively, with better keyboard navigation, focus indicators, and screen reader support.

PHP 8.1+ Minimum

Joomla 5 requires PHP 8.1 or newer. This gives access to modern PHP features like enums, readonly properties, and fibers.

// PHP 8.1+ enums — now usable in Joomla 5
enum ArticleStatus: string {
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

New Debug Toolbar

The old debug output at the bottom of the page is replaced with a modern debug toolbar that shows:

• Page load time
• Memory usage
• Database queries (with EXPLAIN)
• Cache hits/misses
• Language loads

Improved System Requirements

Lower memory footprint and faster page rendering due to Symfony 6 framework optimization.

Joomla 4 Key Features

Joomla 4 was a ground-up rewrite released in 2021. Key features include:

Bootstrap 5

The frontend template Cassiopeia uses Bootstrap 5, providing modern responsive design utilities.

<!-- Bootstrap 5 grid in Cassiopeia -->
<div class="container">
  <div class="row">
    <div class="col-md-8">
      <!-- Main content area -->
    </div>
    <div class="col-md-4">
      <!-- Sidebar -->
    </div>
  </div>
</div>

No jQuery

Joomla 4 does not include jQuery by default. It uses vanilla JavaScript and the ES6 module system. Extensions that require jQuery must include it themselves.

Dark Mode

The administrator interface (Atum template) includes a dark mode option for reduced eye strain.

Workflow Component

The new Workflow component lets you create custom publishing workflows:

Task Scheduler

Replaces cron jobs. You can schedule tasks like cache cleaning, sitemap generation, and search indexing from the administrator interface.

Enhanced Multilingual

Improved language association interface and better language filtering performance.

Joomla 4 Removed Features

Legacy Plugins

Joomla 4 removed many legacy plugins that were deprecated in 3.x:

• Legacy content plugins
• Legacy editor plugins
• Legacy authentication plugins

Media Manager Rewrite

The Media Manager was completely rewritten with a modern interface. The old Media Manager from Joomla 3 is not available.

Search Component Removed

The old Search component (com_search) was deprecated in Joomla 4 and removed in Joomla 5. Smart Search (Finder) is the replacement.

TinyMCE Upgraded

TinyMCE was upgraded from version 4 to version 5, with a new user interface and improved features.

Migrating from Joomla 3.x to 4.x

Pre-Upgrade Checklist

1. Take a full backup of files and database
2. Create a staging copy of your site — never migrate on a live site
3. Update all extensions to versions compatible with Joomla 4
4. Check your template — most Joomla 3 templates are not compatible with Joomla 4
5. Use the Pre-Update Check in the Joomla Update component

Running the Pre-Update Check

1. Go to Components > Joomla Update
2. Click Options and set Update Channel to Next
3. Click Check for Updates
4. Review the Pre-Update Check results

The pre-update check shows:

• PHP version compatibility
• Extension compatibility (green = good, yellow = warning, red = incompatible)
• Database driver compatibility
• Required PHP extensions

Extension Compatibility

Common extension changes in Joomla 4:

The Migration Process

1. In the Joomla Update component, click Install the Update
2. Wait for the update to complete
3. Clear all cache
4. Test the frontend and backend

Post-Migration Tasks

1. Assign the Cassiopeia template as the default
2. Update all extensions to their Joomla 4 versions
3. Test all custom template overrides — many will need updating
4. Enable the System - Page Cache plugin (if not already enabled)
5. Check that Smart Search is working (reindex if needed)
6. Review the error log for any issues

Migrating from Joomla 4.x to 5.x

System Requirements

Joomla 5 requires:

• PHP 8.1.0 or newer (PHP 8.2+ recommended)
• MySQL 8.0+ or MariaDB 10.4+
• PostgreSQL 12.0+

Pre-Upgrade Check

1. Go to System > Joomla Update
2. Click Options and set Update Channel to Joomla Next
3. Click Check for Updates
4. Review the pre-update check

Running the Update

# Alternative: CLI update for Joomla 4 to 5
php /path/to/joomla/cli/joomla.php core:update

Extension Compatibility for Joomla 5

Most Joomla 4 extensions work in Joomla 5 with the backward compatibility layer. However:

• Extensions using MooTools will break
• Extensions using deprecated Joomla 3 APIs will break
• Extensions using the old Search component will break

Post-Upgrade Tasks

1. Clear cache
2. Update the Cassiopeia template to the Joomla 5 version
3. Update all extensions to Joomla 5 versions
4. Check custom overrides
5. Run the Database Fix tool (System > Database > Fix)
6. Review the error log

Pre-Upgrade Checklist (Detailed)

# 1. Backup database
mysqldump -u root -p joomla_db > joomla_backup.sql

# 2. Backup files
tar -czf joomla_files_backup.tar.gz /path/to/joomla/

# 3. Set up staging
cp -r /path/to/joomla /path/to/joomla-staging
mysql> CREATE DATABASE joomla_staging;
mysql> GRANT ALL ON joomla_staging.* TO 'user'@'localhost';

Post-Upgrade Tasks

// Check if your custom plugin is compatible with Joomla 5
// In your plugin code, check for deprecated classes
use Joomla\CMS\Factory;

// Joomla 4 compatible
$db = Factory::getDbo();

// This still works in Joomla 5

Common Mistakes

1. Migrating a live site without testing on staging: Always test the migration on a staging copy first. A failed migration can take your site offline for hours.

2. Ignoring the pre-update check warnings: Yellow warnings may be safe to ignore, but red warnings mean the update will fail or break functionality. Fix these before proceeding.

3. Not updating extensions before migration: Your Joomla 3 extensions may not have Joomla 4 versions. Check each extension's compatibility before starting. Migrate only when all required extensions have compatible versions.

4. Keeping old templates: Joomla 3 templates will not work in Joomla 4 or 5. You must switch to Cassiopeia or purchase a Joomla 4/5-compatible template.

5. Skipping the post-upgrade checklist: After migration, you must clear cache, update extensions, check overrides, and test thoroughly. Skipping these steps leads to broken pages and frustrated visitors.

Practice Questions

1. What PHP version is required for Joomla 5, and why does it matter? Answer: Joomla 5 requires PHP 8.1 or newer. This enables features like enums, readonly properties, and fibers. It also ensures security, as older PHP versions no longer receive security updates.

2. What was removed in Joomla 5 that was present in Joomla 4? Answer: The old Search component was removed entirely. MooTools JavaScript library was removed. The backward compatibility layer for Joomla 3 extensions was removed. Only Joomla 4-compatible extensions work in Joomla 5.

3. What should you do before migrating from Joomla 3.x to 4.x? Answer: Take a full backup, create a staging copy, update all extensions to Joomla 4-compatible versions, install the Cassiopeia template, run the pre-update check, and verify PHP version meets requirements.

4. Challenge: Set up a Joomla 3.10 site with sample data, extensions, and a custom template. Run the pre-update check and identify all compatibility issues. Migrate to Joomla 4.x, documenting each step and any problems encountered. Then migrate from 4.x to 5.x. Create a migration report that includes: backup procedures, pre-update check results, steps taken, issues encountered, and post-upgrade tasks completed.

FAQ

Mini Project

Your task is to plan and execute a full migration from Joomla 3 to Joomla 5.

1. Install Joomla 3.10 with sample data
2. Add several extensions (any free extensions from JED)
3. Install a Joomla 3 template (e.g., Protostar with customizations)
4. Take a full backup (files and database)
5. Review the pre-update check for Joomla 4
6. Resolve any compatibility issues
7. Migrate to Joomla 4.x
8. Complete all post-migration tasks
9. Run the pre-update check for Joomla 5
10. Migrate to Joomla 5.x
11. Complete all post-migration tasks
12. Verify all content and functionality

Create a migration journal documenting every step, every issue encountered, and how you resolved each issue.

What's Next

Now that you understand the differences between versions, learn how to protect your site:

Continue to Lesson 35: Joomla Backups — Akeeba Backup, manual backup, and restore guide.

Related lessons:

• {{< ilink "Joomla" "Joomla Caching" }} — Performance optimization after migration
• {{< ilink "Joomla" "Joomla Database Maintenance" }} — Check database after upgrade