Migrating from Joomla 3

This content was generated with the assistance of AI and should be verified against the official Joomla documentation before being relied on in production.

This sub-section’s Joomla bibliography lists the reference material consulted while preparing these pages.

A site that still runs Joomla 3 cannot simply be updated to the current release. Between Joomla 3.10 and Joomla 4.0 the core was rewritten around namespaces, a new administrator template, a new front-end template, Bootstrap 5 and a new set of requirements, and most extensions and templates written for Joomla 3 do not run unchanged. The official documentation therefore calls the step from 3 to 4 a migration: it is planned like a small project, tested on a copy of the site and finished only when every extension and template has been replaced or updated. This page describes that project for the fictitious Tallpine Hiking Club site (package pkg_tallpine, component com_tallpine, child template cassiopeia_tallpine), which in this scenario has been running on Joomla 3.10 since 2019.

It was written against Joomla 6.2.x on PHP 8.3+ as the destination, and checked on 2026-10-30. Joomla 6.2 is the current release, 5.x is in its security-only period, 4.x is end of life, and 3.x has been end of life since 2023. The release cadence and support windows are in Versions, Release Cycle and Support.

Why 3 to 4 is a migration, not an update

Joomla follows a fixed rhythm: a new major version every two years, each with four minor versions, the last of which (x.4) is a "bridge" release without new features. Inside a major version, updating means replacing core files and running schema updates, and extensions keep working because the backward-compatibility policy forbids breaking changes in minor releases. Between majors, deprecated code is removed and the minimum requirements rise. For Joomla 3 to 4 the consequences were large:

  • the administrator template changed from Isis (and Hathor) to Atum, and the front-end template from Protostar (or Beez3) to Cassiopeia; Protostar is not compatible with Joomla 4 and disappears during the migration

  • the JavaScript and CSS stack moved from Bootstrap 2 and MooTools-era scripts to Bootstrap 5 and vanilla JavaScript, loaded through the Web Asset Manager (see Web Asset Manager); jQuery is no longer a core dependency that every page can assume

  • the extension framework gained namespaces, services/provider.php and dependency injection (see Namespaces, Autoloading and Dependency Injection), and the old J* classes became aliases of namespaced ones

  • the minimum requirements rose: the Developer Manual lists PHP 7.2.5, MySQL 5.6 and PostgreSQL 11.0 for Joomla 4.0, drops SQL Server support, no longer supports the old ext/mysql and ext/pgsql PHP extensions (Joomla uses MySQLi or PDO MySQL, and PDO PostgreSQL), turns MySQL strict mode on by default, and allows only NULL as a date default instead of the invalid 0000-00-00 00:00:00

  • the WebAuthn passwordless login plugin is enabled by default on HTTPS sites and needs the PHP GMP extension

  • Search (com_search) and Weblinks are no longer part of the core; Smart Search replaces the first, and Weblinks continues as a separately maintained extension

  • legacy URL routing is replaced by modern routing

Because of this, Joomla 3 extensions are classified as "compatible with 4", "compatible only through the compatibility plugin", or "must be replaced", and a site builder has to decide this for every row of the Extensions list.

Source: Joomla Manual: Joomla 3.10 to 4.0 upgrade notes

End of life

Joomla 3.10 was the last release of the 3.x series. Its planned end of life was August 2023, and the series was then extended until February 2025, so no 3.x release has received security fixes since. Joomla 4.4, the bridge release of the 4.x series, appeared in October 2023, and the announcement of its end of life states that it receives security patches through 14 October 2025. Both versions are therefore unsupported: a Joomla 3 or Joomla 4 site is exposed to vulnerabilities that will never be fixed in its own series, and hosting providers progressively drop the old PHP versions that Joomla 3 needs. The urgency is therefore not the age of the site’s features but the lack of security fixes.

Source: Joomla announcements: Joomla 3.10 and Joomla 4 end of life

The path

There is no direct jump from 3 to 6. Every major version has to be entered from the previous one’s final release, and each stage is tested before moving on. The documented sequence is:

flowchart LR A[Joomla 3.x site] --> B[Update to latest 3.10.x] B --> C[Pre-update check<br/>channel Joomla Next] C --> D[Replace templates and extensions<br/>on a test copy] D --> E[Joomla 4.4.x] E --> F[Joomla 5.4.x] F --> G[Joomla 6.2.x] E -. "optional stop: 4.4 is also end of life" .-> F

The first hop (3.10.x to 4.4.x) is the migration described on this page. The Joomla User Guide describes the target as "Joomla 4", and Joomla Update installs the newest 4.x release offered, which is 4.4.x. The following hops are ordinary major upgrades, covered in detail in Upgrading Joomla 4 to 5 and Upgrading Joomla 5 to 6. Because 4.4 is itself end of life, plan the whole chain as one project and do not stop at 4.4. The rule that downgrades are not supported means that the backup taken before each hop is the only way back.

Stage Start from Main work

1. Prepare

3.10.x (latest maintenance release)

Fix the database schema, empty the trash, take backups, set up a test copy, inventory extensions and templates.

2. Migrate

3.10.x

Set the update channel to Joomla Next, read the pre-update check, update or remove extensions, install the 4.x core.

3. Stabilise

4.4.x

Run Fix on the database, check Discover, configure the new templates, test, set error reporting back.

4. Continue

4.4.x

Upgrade to 5.4.x (PHP 8.1 or newer, replace com_search, reCAPTCHA removed), then to 6.2.x (PHP 8.3+, BC6 plugin).

Planning

The User Guide’s step-by-step page begins with requirements, which are worth checking before any hour is spent on the migration:

  • the site must be on Joomla 3.10.x; a site on an earlier 3.x release must be updated to 3.10 first

  • every extension must be ready for Joomla 4, or replaceable

  • the server must meet the Joomla 4 technical requirements; if it does not, the site needs a new host or a newer PHP version, which in turn may require updating Joomla 3 extensions that do not run on that PHP version

  • a test location (subdomain, subdirectory, local machine or a separate hosting account) must be available to hold a restored copy of the site

Check the current environment on System → System Information of the live site (the PHP and database versions, and the PHP extensions), and compare it with the destination: Joomla 6.2 needs PHP 8.3 or newer, and its database minimums are discussed in Requirements and Hosting. A host that offers only PHP 7.x cannot run the final destination, so the hosting decision is part of the project, not an afterthought.

Source: Joomla User Guide: Joomla 3 to 4 Planning and Migration Step by Step

The User Guide also states the realistic alternative: when a site skips several major versions and relies on many outdated extensions, rebuilding the site on the latest version, and importing only content and users, can be less work than a chain of upgrades. For the Tallpine site this is the question to answer at this point: a small content site with two or three extensions migrates; a site built on a discontinued page builder is often better rebuilt on a child template of Cassiopeia (see Child Templates).

Preparing the 3.10 site

Do this on the live site, before copying it:

  1. Update Joomla to the latest 3.10.x maintenance release.

  2. Open Extensions → Manage → Database and press Fix if the schema is out of date. A migration started from an inconsistent schema fails in ways that are hard to attribute.

  3. Empty the trash of articles, categories and menu items. Items left in the trash can cause errors during the migration.

  4. Take a full backup (files and database) and keep it untouched (see Backups and Recovery).

The User Guide asks for further backups at fixed moments: after the test restore, after the extension clean-up, before the 4.x update itself, after each major step, and a last one of the 3.10 site just before the new site goes live. A backup that has never been restored is not a backup; the restore into the test location is the test.

Restoring a copy into a test location

The following script restores a Joomla 3 dump into a staging directory and database. The file names and host names are placeholders, and the database credentials are read from the environment so that they are not written into a file or a shell history.

#!/usr/bin/env bash
# Restore a Joomla 3.10 backup into a staging directory (run on the staging machine).
set -euo pipefail

: "${STAGING_DB_PASSWORD:?set STAGING_DB_PASSWORD in the environment}"
STAGING_DIR=/var/www/tallpine-staging
STAGING_DB=tallpine_staging

mkdir -p "$STAGING_DIR"
tar -xzf tallpine-3.10-files.tar.gz -C "$STAGING_DIR"

mysql --user=tallpine_staging --password="$STAGING_DB_PASSWORD" \
  -e "CREATE DATABASE IF NOT EXISTS ${STAGING_DB} CHARACTER SET utf8mb4;"
mysql --user=tallpine_staging --password="$STAGING_DB_PASSWORD" "$STAGING_DB" \
  < tallpine-3.10-db.sql

# Point the copy at the staging database and prevent it from sending mail or being indexed.
sed -i "s/^\(\s*public \$db = \).*/\1'${STAGING_DB}';/" "$STAGING_DIR/configuration.php"
sed -i "s/^\(\s*public \$offline = \).*/\1'1';/" "$STAGING_DIR/configuration.php"

Source: Joomla User Guide: Joomla 3 to 4 Planning and Migration Step by Step

Edit the mail settings of the copy as well (System → Global Configuration → Server → Mail), because a staging site that sends newsletters or password resets to real members is a common and embarrassing accident. Also note that the copy contains personal data, so it falls under the same retention rules as production (see Privacy and Action Logs).

The pre-update check

Joomla 3.10 was designed as the stepping stone: it contains a pre-update check that reads the compatibility information of the extensions against the target version. The User Guide procedure is:

  1. Open Components → Joomla Update in the Joomla 3.10 administrator.

  2. Open Options and set the Update Channel to Joomla Next, then Save & Close. The channel makes the 4.x release visible as an update.

  3. Review the compatibility results on the update page and on the Extension Pre-Update Check tab.

  4. Do not install the update yet.

The check lists each third-party extension with a status: compatible, not compatible, or missing information from its update server. An extension that shows "Missing Compatibility Tag" is not necessarily incompatible; the vendor has not published the information. The User Guide advises confirming with the developer. The check relies on update servers (see Update Servers and the JED), so an extension that was installed manually and never had an update server will show no information. In Joomla 4 and later, the check is described by the project itself as a guide rather than a guarantee; the same wording is used for the later upgrades (see Updating Joomla and Automated Core Updates, section "The pre-update check"). Treat a green result as a reason to test, not as a reason to skip testing.

Source: Joomla User Guide: Joomla 3 to 4 Planning and Migration Step by Step

Replacing templates and extensions

This is where most of the effort goes. Work in Extensions → Manage → Manage on the test copy, filter by type, and start with packages, because uninstalling a package removes the components, modules and plugins that belong to it.

Inventory first

The Extensions list is a good start, but a query shows what the migration will have to deal with. Run it on the copy; PREFIX_ stands for the table prefix chosen at installation.

-- Third-party extensions of the Tallpine Joomla 3 site (core extensions have protected = 1).
SELECT extension_id, type, element, folder, client_id, enabled
FROM PREFIX_extensions
WHERE protected = 0
ORDER BY type, folder, element;

-- Templates and their styles; Protostar styles disappear in the migration.
SELECT id, template, client_id, home, title
FROM PREFIX_template_styles
ORDER BY client_id, template;

Source: Joomla User Guide: Joomla 3 to 4 Planning and Migration Step by Step

For each row decide one of four things: remove (no longer used), update (a Joomla 4 version exists), replace (another extension does the job, often a core feature that did not exist when it was installed) or rewrite (own code, such as com_tallpine). Do not remove the extensions of the Joomla Project itself.

Templates

  • Protostar is not compatible with Joomla 4; it disappears during the migration. Uninstall the other core templates except Beez3 (front end) and Isis or Hathor (administrator), and keep one of them as the default until the migration is done. The User Guide also lists leftovers to remove: plg_content_geshi, Bluestork, Beez_20, Beez5 and Atomic.

  • Cassiopeia is the Joomla 4 core front-end template, and Atum the administrator template. A third-party template needs a release explicitly built for Joomla 4. Many Joomla 3 templates were built on the Bootstrap 2 or 3 markup and MooTools or jQuery scripts, and cannot be fixed by a small change.

  • For the Tallpine site, the old customised Protostar copy is not ported. A new child template cassiopeia_tallpine is created instead; child templates are the supported way of customising Cassiopeia (see Child Templates and Cassiopeia and Cassiopeia Extended). Template overrides copied from Joomla 3 must be redone from the Joomla 4 files, because the layouts and CSS classes differ (see Template Overrides and Alternative Layouts).

  • Positions used by the old template (for example position-7 in Protostar) have to be mapped to the positions of the new one, otherwise the modules assigned to them are not displayed (see Modules and Positions).

Extensions

  • Search (com_search) is not part of Joomla 4; Smart Search is its replacement (see Smart Search). Weblinks is distributed and maintained separately.

  • Extensions that have a Joomla 4 version: update them while still on 3.10 whenever the vendor supports that, as the User Guide advises, and re-run the pre-update check.

  • Extensions with no Joomla 4 version: look for an alternative (often a core feature such as custom fields, workflows or tags) or for the extension’s successor in the Joomla Extensions Directory.

  • Joomla 4 ships the Behaviour - Backward Compatibility plugin to let some Joomla 3 code run, mainly the old J* class aliases and legacy MVC base classes. It is a bridge, not a goal: it is supported through the Joomla 5 lifetime and removed afterwards. The plugin’s successor for the 5.4 to 6 step is described in Error Handling and Legacy APIs, where the removals that matter for extension code are listed. Do not rebuild a design on it.

Own extensions: a manifest for Joomla 4

An extension such as com_tallpine that was written for Joomla 3 has to be rewritten rather than patched. At the very least its manifest changes. The Joomla 3 manifest declared the version and listed the files, and its classes used the JControllerLegacy, JModelItem and JFactory family, without namespaces:

<?xml version="1.0" encoding="utf-8"?>
<!-- Joomla 3 style: no namespace, legacy MVC, installed by a script.php class -->
<extension type="component" version="3.10" method="upgrade">
  <name>com_tallpine</name>
  <version>1.4.0</version>
  <scriptfile>script.php</scriptfile>
  <files folder="site">
    <filename>tallpine.php</filename>
    <folder>models</folder>
    <folder>views</folder>
  </files>
</extension>

Source: Joomla Manual: Joomla 3.10 to 4.0 upgrade notes

The Joomla 4 and later form declares a namespace and the service provider that wires the component:

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" method="upgrade">
  <name>com_tallpine</name>
  <version>2.0.0</version>
  <namespace path="src">Tallpine\Component\Tallpine</namespace>
  <scriptfile>script.php</scriptfile>
  <files folder="site">
    <folder>src</folder>
    <folder>tmpl</folder>
  </files>
  <administration>
    <files folder="admin">
      <folder>services</folder>
      <folder>src</folder>
      <folder>tmpl</folder>
    </files>
  </administration>
</extension>

Source: Joomla Manual: Manifest Files

The remainder of that rewrite (MVC factory, dispatcher, the router, language files) is covered in Extension Types, Manifests and Packaging and Component MVC: Administrator. A rewritten component also needs its data to survive: keep the table names and write an update script rather than recreating them (see Installer Scripts and SQL Updates).

Running the migration (3.10 to 4.4)

When the test copy is clean and a fresh backup exists, the User Guide’s sequence for the update itself is:

  1. Set System → Global Configuration → Server → Error Reporting to Maximum, then Save & Close. Errors that would otherwise be hidden show up during and after the update.

  2. Check that the update to Joomla 4 appears on the Joomla Update page, with the channel Joomla Next. If it does not, purge the cache under Extensions → Manage → Update (the update information is cached).

  3. Press Install the Update. The process takes about two minutes, and an administrator is typically logged out at the end, so log in again.

Then, after the update:

  1. Open System → Maintenance → Database and press Fix if errors are reported.

  2. Open System → Install → Discover and install any extension that is shown there.

  3. Verify that the front end loads, install and configure the new template and the replacement extensions, and run a broken-link checker.

  4. Test everything, then set Error Reporting back to System Default.

For the cut-over, the guide suggests moving the 4.x site to the root of the domain, retesting, checking .htaccess against the Joomla 4 htaccess.txt, and removing the 3.10 copy within a couple of days; development copies should be removed or updated, since an old Joomla 3 copy left on the server is a vulnerable site. The configuration files of Joomla 4 are described in configuration.php and .htaccess.

Source: Joomla User Guide: Joomla 3 to 4 Planning and Migration Step by Step

Command-line check after the migration

Once on 4.4, the command line is useful for a scripted check that nothing was missed. The commands below list the available commands, the update information and the installed extensions; on 4.4 the exact set of commands is shown by list.

cd /var/www/tallpine-staging
php cli/joomla.php list                # commands offered by this version
php cli/joomla.php core:check-updates  # is a newer 4.x or 5.x release offered?
php cli/joomla.php extension:list      # installed extensions, to compare with the inventory

Source: Joomla User Guide: Using the CLI

The CLI is described in Command Line Interface. Which commands exist on 4.4 differs from 6.2, so rely on the output of list for the installed release.

Common errors and pitfalls

  • Starting from the wrong version. The update is offered from 3.10.x only. A site on 3.9 or earlier first has to be updated to the last 3.10; do not look for an alternative route.

  • Update not shown. The channel is not Joomla Next, the update cache is stale, or the server does not meet the requirements. Purge the cache under Extensions → Manage → Update and read the pre-update check.

  • White page or HTTP 500 after the update. Usually an extension or template that does not support Joomla 4, or a PHP extension that is missing (MySQLi or PDO, GMP for WebAuthn). Error Reporting set to Maximum, and the web server and PHP logs, show the cause.

  • MySQL strict mode. Joomla 4 enables strict mode. Queries from custom code that insert '' into numeric columns or use 0000-00-00 00:00:00 as a date default fail where Joomla 3 accepted them. Dates in the Joomla 4 schema are NULL by default.

  • Missing modules. Positions of the old template do not exist in Cassiopeia; modules disappear until they are assigned to a position of the new template.

  • Menu and URL changes. Legacy routing is replaced by modern routing. Compare the sitemap before and after, and keep the old URLs working with redirects (see SEO, SEF URLs, Redirects and Schema.org).

  • Search results gone. com_search is not present; the Smart Search index has to be built (see Smart Search).

  • Trashed items. Left in the trash they can break the migration, which is why the trash is emptied beforehand.

  • Stopping at 4.4. A site that stays on 4.4 is as unsupported as the Joomla 3 site it replaced.

Security notes

  • The test copy holds real data. Keep it behind HTTP authentication or an allow list, take it offline for the public and disable outgoing mail.

  • A backup archive or SQL dump in the web root is a copy of the site; store backups outside the document root.

  • Rotate the database password and consider changing the Joomla $secret after restoring an old site into a new location, as described in Backups and Recovery.

  • Delete the Joomla 3 copy after the cut-over. Old Joomla 3 directories left on a shared server are often the way an attacker enters.

  • After the migration enable multi-factor authentication for administrators (available in the core since Joomla 4.2; see Security Hardening, MFA and Passkeys).

After 4.4: continuing to 5.4 and 6.2

Once the Joomla 4.4 site is stable, the next hops are shorter because they share the same architecture.

4.4 to 5.4

The User Guide’s Joomla 4 to 5 page requires the site to be on 4.4.x, PHP 8.1 or newer, and one of the databases MySQL 8.0.13, MariaDB 10.4 or PostgreSQL 12 or newer. Remove com_search before the upgrade, since Joomla 5 relies on Smart Search, and replace Google reCAPTCHA, which is removed in Joomla 5, with another captcha. The Backward Compatibility plugin is enabled automatically during the upgrade; it can be disabled once all extensions work without it. If access to the administrator is lost, set enabled to 1 on its row in the extensions table. The channel Joomla Next is used again. The guide also tells to configure the Schema.org plugin and to check Smart Search afterwards. The whole procedure is on Upgrading Joomla 4 to 5.

Source: Joomla User Guide: Joomla 4 to 5 Planning and Upgrade Step by Step

Joomla 5.0 also removed the ES5 assets and the old reCAPTCHA plugin. The updates section of the Developer Manual has a page for every pair of minor versions, from 3.10 to 4.0 through 6.2 to 6.3 and 6.4 to 7.0.

5.4 to 6.2

The upgrade from 5.4 to 6 needs the latest 5.4.x, the old Backward Compatibility plugin disabled, the new Behaviour - Backward Compatibility 6 plugin enabled (they cannot both be on) and the Joomla Next channel. Joomla 6.0 removed JPATH_PLATFORM, \Joomla\CMS\Input, the CMS application base classes and CMSObject from AdminModel::getItem(), among other things; the details, the 7.0 removals and a checklist for pkg_tallpine are in Error Handling and Legacy APIs and Upgrading Joomla 5 to 6. After 6.x is reached, the core can update itself with Automated Core Updates (see Updating Joomla and Automated Core Updates), and extensions keep up through update servers.

Source: Joomla Manual: Joomla 5.4 to 6.0 upgrade notes

Where older books and tutorials are outdated

  • Joomla! 4 Masterclass (2023) targets Joomla 4.x, which ended on 14 October 2025, and does not describe a migration from Joomla 3. Its description of child templates as a recent feature and its links to docs.joomla.org/J4.x pages are out of date; the current documentation is the User Guide (guide.joomla.org) and the Developer Manual (manual.joomla.org).

  • Developing Extensions for Joomla! 5 (2023) assumes the extension is written for 5.0 and does not cover porting a Joomla 3 extension; its code is a good model for the rewritten com_tallpine, but the events, plugin properties and installer script classes it shows have since changed (see Plugin Development and Events).

  • Tutorials written for the Joomla 3 to 4 jump often say "update to 4.0". The target now is the last 4.x release, and the migration continues to 5.4 and 6.2. They also describe tools that are not part of Joomla (migration extensions, backup extensions) as if they were part of the procedure; the official procedure uses only Joomla Update, and a third-party backup tool is a convenience.

  • The legacy wiki pages for the Joomla 3 to 4 migration at docs.joomla.org are marked obsolete or have been replaced by the User Guide; use them only for details the new documentation lacks, such as the list of compatibility changes of the 4.0 release.

A checklist for the Tallpine site

  1. Update the live site to the latest 3.10.x, fix the database, empty the trash.

  2. Take and verify a full backup; restore it into a staging copy that cannot send mail.

  3. Choose the channel Joomla Next on the copy and read the pre-update check.

  4. Remove unused extensions and templates, update the rest, replace what has no Joomla 4 version.

  5. Build the new child template cassiopeia_tallpine; map the module positions.

  6. Rewrite com_tallpine (namespace, manifest, services) and add an update script for its tables.

  7. Install the 4.4 update with Error Reporting at Maximum; run Fix, Discover and the broken-link check.

  8. Continue to 5.4 and then 6.2 on the copy, then repeat the whole chain on production with fresh backups.

  9. Remove the Joomla 3 copy and enable MFA for administrators.

References