The Joomla Behaviour – Backward Compatibility plugin is a temporary bridge that restores selected legacy classes and assets so older extensions can keep running after a major Joomla upgrade. It is not a performance plugin, a security plugin, or proof that an extension is fully compatible. On Joomla 5 it bridges Joomla 4-era code. On Joomla 6, the separate Behaviour – Backward Compatibility 6 plugin bridges selected Joomla 5-era code. You should keep the appropriate bridge enabled while it is needed, then update or replace dependent extensions and prove the site works with it disabled.
The most important detail is easy to miss: Joomla 5.4 has two compatibility plugins, and they have opposite roles during an upgrade to Joomla 6. The unnumbered Joomla 5 plugin must be disabled. The Joomla 6 plugin must be enabled. Joomla's pre-update checker enforces this configuration before Live Update can continue.
This guide explains the history, purpose, options, overhead, risks, safe disable test, recovery procedure, developer migration work, and exact settings for Joomla 4.4, 5.x, and 6.x. It is based on the official Joomla compatibility plugin documentation, Joomla 5.4 to 6.x migration documentation, backward compatibility policy, and current Joomla source.
What you will learn
- Why Joomla created compatibility plugins
- When the first plugin appeared and how the bridge model evolved
- Which plugin belongs to Joomla 5 and which belongs to Joomla 6
- What every option actually loads
- Whether leaving the plugin enabled affects speed, security, or upgrades
- When you can safely disable it
- How to find the extension that still depends on it
- How to recover if disabling it breaks the frontend or Administrator
- What extension developers must change for native compatibility
For hands-on upgrade help, see Joomla upgrade services or hire Joomla developers.
The short answer for every Joomla version
| Your site |
Plugin state |
What it means |
| Joomla 4.4 preparing for Joomla 5 |
Behaviour – Backward Compatibility is staged for the Joomla 5 transition |
The bridge becomes active for the major upgrade |
| Joomla 5.0 to 5.3 |
Unnumbered plugin often enabled |
Older Joomla 4 extensions may still depend on class aliases or asset shims |
| Joomla 5.4 staying on Joomla 5 |
Unnumbered plugin may remain enabled temporarily |
Disable it on staging to discover technical debt |
| Joomla 5.4 preparing for Joomla 6 |
Disable unnumbered plugin; enable Backward Compatibility 6 |
Required by the pre-update checker |
| Joomla 6 upgraded from 5.4 |
Backward Compatibility 6 is normally enabled |
It protects the first boot while extensions transition |
| Fresh Joomla 6 installation |
Backward Compatibility 6 is installed but disabled by default |
New extensions should not need the bridge |
| Joomla 6 after every extension passes native testing |
Backward Compatibility 6 can be disabled |
This is the desired end state |
Current context as of September 2026: Joomla 6.1.3 and 5.4.8 are the latest stable maintenance releases. Joomla 5.4 remains the bridge line to Joomla 6. Check the Joomla roadmap before planning production work.
What backward compatibility means in Joomla
Backward compatibility means newer Joomla code continues to accept supported older APIs, data structures, or behavior for a defined period. Joomla guarantees compatibility within a major series, subject to exceptional security fixes. A new major series is where deprecated technical debt can be removed.
Joomla's policy says deprecated code can be moved into a compatibility plugin. That lets the core become cleaner without forcing every third-party extension to be rewritten on the exact day a major version ships.
An extension is only fully compatible with a Joomla major version when it works with that version's compatibility plugin disabled. A directory badge that says "works on Joomla 6 with compatibility plugin" is useful, but it is not the same as native Joomla 6 compatibility.
Why Joomla introduced the plugin
Joomla had accumulated years of deprecated APIs while moving from global class names toward PHP namespaces, replacing old JavaScript assets, and modernizing its framework.
For example, older extensions used global classes such as JFactory, JTable, JPlugin, and JText. Namespaced replacements started arriving during the Joomla 3 era. Removing every alias at once in Joomla 5 would have broken many otherwise usable extensions.
The compatibility plugin solved four product problems:
- Safer first boot after a major update. System and behaviour plugins may execute before an administrator can log in and fix them.
- Time for extension developers. Vendors could support the new major while removing deprecated dependencies in stages.
- A measurable migration path. Administrators can disable individual shims or the entire plugin to discover what remains.
- Cleaner core. Deprecated code can leave the main core without disappearing immediately from upgraded sites.
It was implemented in the special behaviour plugin group because it must load before other plugins that might call a legacy class during initialization. Joomla explicitly warns third-party developers not to create their own behaviour plugins because this group exists for an internal early-loading purpose and may change in the future.
Timeline: when it started and how it evolved
| Date / release |
What happened |
Why it matters |
| Joomla 3.x era |
Namespaced replacements gradually superseded many global J* classes |
Extensions had a long deprecation runway |
| Joomla 4.4 |
Joomla 5 transition code was staged before the major update |
The bridge could be ready before Joomla 5 files replaced the site |
| Joomla 5.0, October 2023 |
Behaviour – Backward Compatibility became the Joomla 4 to 5 bridge |
It supplied class aliases and web asset shims |
| Joomla 5.4, October 2025 |
Behaviour – Backward Compatibility 6 was installed and enabled as a no-op bridge seed |
It would already be active when Joomla 6 code arrived |
| Joomla 6.0, October 2025 |
The old Joomla 5 bridge was replaced by Backward Compatibility 6 |
Selected Joomla 5-era APIs moved behind the new bridge |
| Joomla 6.x today |
Upgraded sites can use compat6 temporarily; fresh installs keep it disabled |
Native compatibility remains the target |
The official Joomla 5 plugin manifest identifies version 5.0.0, while its PHP class is marked @since 4.4.0. That reflects the staging strategy: place the bridge during the final minor of the old major so it is available at the first boot of the new major.
The two plugins people confuse
Behaviour – Backward Compatibility
This is the Joomla 5 compatibility plugin. Its extension element is compat, in the behaviour folder.
It bridges selected Joomla 4-era dependencies while running Joomla 5. Before upgrading from Joomla 5.4 to Joomla 6, it must be disabled. If disabling it breaks the site, one or more extensions are not ready for Joomla 6.
Behaviour – Backward Compatibility 6
This is the Joomla 6 compatibility plugin. Its extension element is compat6, also in the behaviour folder.
It is installed and enabled on Joomla 5.4 but deliberately does no compatibility work while Joomla 5 code is still running. It is waiting for the Joomla 6 codebase. It must be enabled before the Joomla 5.4 to 6 upgrade.
After the site runs successfully on Joomla 6 and every extension is native, this plugin can be disabled.
What the Joomla 5 plugin options do
The Joomla 5 plugin has three separately configurable options.
| Option |
What it supplies |
What dependence looks like |
| Classes Aliases |
Aliases for classes renamed or moved into namespaces |
Errors such as Class "JTable" not found after disabling |
| ES5 Assets |
Empty compatibility entries for removed .es5 web assets |
WebAssetManager throws an asset-not-found exception |
| Removed Assets |
Empty registry entries for Joomla 4 assets removed in Joomla 5 |
An extension requests an old CSS/JS asset by name |
The ES5 and removed-asset shims are usually empty. They prevent exceptions; they do not recreate obsolete browser code or restore an old interface. If an extension relied on the actual removed asset behavior, an empty registry entry may stop the crash but cannot guarantee that the feature still works.
Source: Joomla 5 compatibility plugin implementation.
What the Joomla 6 plugin options do
Joomla 6's compat6 plugin has a different set of bridges.
| Option |
What it supplies |
Typical dependency |
| Classes Aliases |
Aliases for renamed or moved classes |
Old global or moved class references |
| Include Deprecated Classes |
Loads selected Joomla CMS classes moved into plugins/behaviour/compat6/classes |
Code using packages removed from Joomla 6 core |
| Removed Assets |
Empty registry entries for assets removed from Joomla 5 to 6 |
Old WebAssetManager dependencies |
Concrete examples documented for Joomla 6 include the old Joomla\CMS\Input namespace and the deprecated Joomla\CMS\Filesystem package. Native code should move to Joomla\Input and Joomla\Filesystem. Joomla's removed and backward-incompatible list is the authoritative developer checklist.
Source: compat6 implementation.
What the plugin does not do
The plugin is intentionally limited. It does not:
- Make every Joomla 3 or Joomla 4 extension work on Joomla 5 or 6
- Fix PHP version incompatibility
- Rewrite an obsolete extension manifest
- Repair database schemas or failed update SQL
- Restore removed third-party libraries
- Convert legacy event handling automatically
- Fix template overrides after core markup changes
- Make an abandoned extension secure
- Replace extension updates from the vendor
- Downgrade Joomla or reverse an upgrade
If an extension claims support only because the compatibility plugin hides one missing class, test its complete workflow. Loading without an exception is not the same as functioning correctly.
Benefits of keeping it enabled during transition
Safer major upgrades
The first request after an update may load third-party system plugins before you can reach Administrator. Early class aliases reduce the chance of an immediate fatal error.
Controlled extension migration
You can upgrade the site platform first, then replace or refactor extensions on staging in a managed sequence.
Faster diagnosis
Turning options off one at a time can reveal whether an extension depends on class aliases, deprecated classes, or asset shims.
Longer useful life for maintained extensions
A vendor can ship a release that works on two Joomla majors while completing native migration work.
Does leaving it enabled hamper the website
Usually not in a noticeable way. The plugin loads early, may include a class map, registers a namespace for legacy classes, and may add small web asset registry files. On a normal site, that overhead is generally minor compared with database queries, page builders, images, and network latency.
However, "small runtime overhead" is not the same as "leave it forever." The larger costs are operational:
- It can hide extensions that are not truly ready for the next major version.
- It keeps legacy code paths available.
- It delays vendor accountability and cleanup.
- It can make a future major upgrade fail when that bridge is removed.
- Troubleshooting becomes harder because the site behaves differently with and without shims.
There is no honest universal millisecond figure. Impact depends on enabled options, opcode cache, extension code, and request type. Benchmark your site before and after on staging if performance is a concern.
Security implications
Enabling the official core plugin is not inherently a vulnerability. It is maintained as part of Joomla and exists for supported upgrade paths.
The risk is dependency, not the switch itself. An old extension that requires legacy compatibility may also contain outdated coding patterns or unpatched vulnerabilities. The plugin does not audit, patch, sandbox, or secure that extension.
Use this rule:
Compatibility is a bridge to updated code, not permission to keep abandoned code.
Keep Joomla core and extensions patched. Remove extensions you no longer use. Check compatibility and security notices in the Joomla Extensions Directory.
When you can safely turn it off
Turn off the active compatibility plugin when all these statements are true:
- Every installed component, module, plugin, template, and package explicitly supports your current Joomla major.
- The extension vendor says native support, not only "works with compatibility plugin."
- You tested frontend, Administrator, forms, login, search, checkout, scheduled tasks, CLI, API, and email on staging.
- Debug logging shows no missing legacy classes or assets.
- You have a tested backup and rollback point.
- The site remains stable through at least one representative business workflow.
For a fresh Joomla 6 site, leave compat6 disabled unless a known extension requires it. For an upgraded Joomla 6 site, do not race to disable it on production immediately after the core update. First prove the site, update extensions, then run the disable test on staging.
When you should not turn it off
Do not disable it directly on production when:
- You have no recent backup
- You do not have staging
- An extension vendor explicitly requires it
- The site uses old custom code nobody has audited
- A Joomla 5 site still throws
JFactory, JTable, JPlugin, or similar legacy-class errors
- A Joomla 6 site still uses packages documented as moved into compat6
- A release or checkout is in progress
Keeping it enabled temporarily is safer than causing an outage. The correct follow-up is to identify the dependency, not pretend the plugin must stay forever.
Safe disable procedure
Step 1: Clone production to staging
Use the same PHP version, database engine, web server, and extensions. A different environment can hide or invent compatibility errors.
Step 2: Update everything first
Update Joomla within the current major. Update every extension and template. Remove unused extensions instead of merely disabling them.
Step 3: Back up and test the restore
A backup you have never restored is only a hopeful archive.
Step 4: Enable maximum diagnostics on staging
In Global Configuration:
- Debug System: Yes
- Error Reporting: Maximum
- Log Deprecated API: enable if available in your Joomla version and logging configuration
Do not leave verbose errors exposed on production.
Step 5: Disable options one at a time
Start with removed assets, then ES5 assets or deprecated classes, then class aliases. Clear Joomla cache after every change. This isolates the type of dependency.
Step 6: Test more than the homepage
Use this test matrix:
| Area |
Tests |
| Frontend |
Home, article, category blog, search, contact form, multilingual switcher |
| Administrator |
Login, article edit/save, media, menus, modules, users, configuration |
| Extensions |
Checkout, form submission, subscriptions, imports, exports, backups |
| Background |
Scheduled tasks, cron, queue jobs, CLI commands |
| Integration |
REST API, webhooks, SMTP, payment callbacks |
| Template |
Menu, modal, tabs, tooltips, JavaScript widgets, overrides |
Step 7: Disable the whole plugin
If all individual options pass, disable the plugin and repeat the matrix. Keep logs open for fatal errors and deprecation messages.
Step 8: Fix the dependency, then retest
Update, replace, or refactor the responsible extension. Do not just re-enable the bridge and close the ticket.
Joomla 5.4 to Joomla 6: exact plugin states
Before upgrading:
| Plugin |
Required state on Joomla 5.4 |
| Behaviour – Backward Compatibility |
Disabled |
| Behaviour – Backward Compatibility 6 |
Enabled |
The pre-update checker and CLI core:update verify both conditions. If either check fails, Joomla blocks the major update. This is deliberate. It prevents an incompatible Joomla 4-era extension from crashing the site halfway through a Joomla 6 update.
Official procedure: Joomla 5 to 6 planning and upgrade.
The correct Joomla 5 to 6 workflow
- Update the current site to Joomla 5.4.x.
- Update every extension and template.
- Confirm Backward Compatibility 6 is installed and enabled.
- Disable the unnumbered Backward Compatibility plugin.
- Clear cache and test the complete site while still on Joomla 5.4.
- If anything breaks, re-enable the old plugin and fix the extension on Joomla 5.4.
- Repeat until Joomla 5.4 runs without the old bridge.
- Back up and verify restore.
- Run Joomla's pre-update check.
- Upgrade to Joomla 6.
- Test with compat6 enabled.
- Migrate remaining Joomla 5-era dependencies and later test compat6 disabled.
The important safety feature is step 5. Finding the fatal error before the major update is safer than finding it during a partially completed update.
How to identify the extension that depends on it
Read the first useful stack frame
A fatal error often names JTable, JFactory, JPlugin, JText, an old namespace, or a removed asset. The first stack frame inside /components, /plugins, /modules, /templates, or /administrator/components usually identifies the owner.
Search custom and third-party code
Examples worth searching for on a Joomla 5 site:
JFactory
JTable
JPlugin
JText
JLoader
JFormField
Do not assume every search match is active or wrong. Vendors sometimes provide their own aliases. Use the stack trace to connect a match to a failing request.
For Joomla 6, also search imports from removed CMS packages listed in the migration guide, such as:
use Joomla\CMS\Input\Input;
use Joomla\CMS\Filesystem\File;
use Joomla\CMS\Filesystem\Folder;
Replace them using the official Joomla 6 migration notes rather than blind search-and-replace.
Disable extensions in batches on staging
When the stack trace is unclear, disable non-core system plugins in small batches. System plugins can execute on every request and are frequent causes of an Administrator lockout.
Check WebAssetManager exceptions
An error naming an asset instead of a class points to ES5 or removed-asset compatibility. Update the extension's asset declaration and calls.
Recovery when disabling the plugin breaks the site
Fast recovery through Administrator
If Administrator still works, open System → Manage → Plugins, search Backward Compatibility, and enable the plugin again. Clear cache.
Database recovery when Administrator is down
Open the #__extensions table (replace #__ with your table prefix). Find:
folder = behaviour, element = compat for the Joomla 5 bridgefolder = behaviour, element = compat6 for the Joomla 6 bridge
Set enabled = 1 for the plugin you need to restore. Do not enable both blindly during a Joomla 5.4 to 6 upgrade attempt. Restore the state appropriate for the Joomla version, then fix the underlying extension on staging.
Restore instead of downgrading
Joomla does not support downgrading a core upgrade. If the update itself failed or data changed, restore the pre-upgrade backup. Do not copy old core files over a newer database and call it a rollback.
Can you uninstall the compatibility plugin
Do not uninstall or delete this core plugin. Disable it when it is no longer needed.
Keeping the files installed lets Joomla updates maintain them and gives you a supported recovery path. Manually deleting core plugin files can create database/file mismatches and complicate later updates.
Can you disable only some options
Yes, and that is the best diagnostic method.
On Joomla 5, an extension may need class aliases but not ES5 or removed assets. On Joomla 6, it may need deprecated classes but not removed asset placeholders. Turn options off individually on staging, clear cache, and run the test matrix.
Partial disablement reduces the compatibility surface while showing the vendor exactly what remains.
Extension developer migration checklist
An extension developer should:
- Replace global
J* class names with supported namespaced classes.
- Replace removed CMS packages with current framework packages where Joomla documents a replacement.
- Stop requesting removed ES5 or WebAssetManager entries.
- Use supported concrete event classes and subscriber patterns where applicable.
- Test installation, update, uninstall, and schema changes.
- Test frontend, Administrator, CLI, API, and scheduled-task contexts.
- Run the extension with all compatibility options disabled.
- Declare compatibility accurately in the update server and Joomla Extensions Directory.
The Joomla backward compatibility policy explains what core promises and what it does not. Internal, private, final, and third-party APIs are not automatically protected.
Common errors after disabling
| Error or symptom |
Likely dependency |
Correct response |
Class "JTable" not found |
Joomla 4-era global class alias |
Update/refactor the extension |
Class "JPlugin" not found |
Very old plugin base class |
Use current CMSPlugin and service registration |
| Web asset not found |
Removed or ES5 asset name |
Update asset JSON/calls; do not rely on empty shim |
| Blank frontend but Admin works |
Site plugin/module/template dependency |
Enable debug on staging and inspect stack trace |
| Both frontend and Admin fail |
Early-loading system/behaviour plugin |
Re-enable via database, then isolate extension |
| Joomla 6 pre-update check blocks |
Wrong states for compat and compat6 |
Disable old plugin; enable compat6 |
| Site works enabled but fails disabled |
Extension is bridge-compatible, not native |
Update, replace, or refactor |
Myths and facts
| Myth |
Fact |
| The plugin converts Joomla 4 extensions to Joomla 5 |
It supplies selected aliases and shims; it does not rewrite extension code |
| Enabled means the site is insecure |
The core plugin is supported; the concern is outdated dependent extensions |
| Disabled always makes Joomla faster |
Runtime savings are normally small; clean architecture is the bigger benefit |
| Joomla 5.4 should have both plugins disabled before Joomla 6 |
Wrong. Old compat disabled; compat6 enabled |
| A Joomla 6 badge means no bridge is needed |
Check whether the vendor means native compatibility or compatibility with compat6 |
| If the site loads, the extension is compatible |
You must test saves, jobs, forms, API, email, and other workflows |
| Delete the plugin when done |
Disable it; do not delete core plugin files |
Recommended operating policy
Use a simple policy across client sites:
- Record the active compatibility plugin and option states in the maintenance runbook.
- Review the state after every extension release cycle.
- Run a disabled test on staging at least quarterly.
- Reject new extensions that require a bridge without a vendor migration plan.
- Make "runs with compatibility plugin disabled" an acceptance criterion for custom extension work.
- Remove abandoned extensions before the next Joomla major.
This turns the plugin from permanent mystery infrastructure into measurable migration debt.
Key takeaways
- Joomla introduced compatibility plugins to make major upgrades safer while removing deprecated code from core.
- The Joomla 5 plugin bridges selected Joomla 4 dependencies; compat6 bridges selected Joomla 5 dependencies.
- On Joomla 5.4 before Joomla 6, disable the unnumbered plugin and enable Backward Compatibility 6.
- Leaving the correct plugin enabled usually has minor runtime overhead, but it can hide extension debt.
- The goal is native compatibility, proven on staging with the plugin disabled.
- Never delete the core plugin. Disable it and keep a tested recovery path.
- A successful homepage is not enough; test Admin, forms, jobs, API, email, and extension workflows.
Frequently asked questions
What is the Joomla Behaviour – Backward Compatibility plugin?
It is a core transition plugin that restores selected legacy classes and asset registrations after a major Joomla upgrade so older extensions have time to become native.
When was the plugin introduced?
The Joomla 5 bridge was staged in Joomla 4.4 and became the compatibility layer for Joomla 5.0 in October 2023. The Joomla 6 bridge was staged in Joomla 5.4 and became active with Joomla 6.0 in October 2025.
Should I keep the plugin enabled?
Keep it enabled while a maintained extension genuinely needs it. Update or replace that dependency and test disabling the plugin on staging.
Does the compatibility plugin slow down Joomla?
Usually not noticeably. It loads aliases, optional legacy classes, and small asset registries. The bigger cost is hidden technical debt rather than page-load time.
Is it a security risk?
The official plugin itself is supported Joomla core code. The risk is that it may keep an old, potentially vulnerable third-party extension running. It does not patch extensions.
Can I turn it off on Joomla 5?
Yes, after testing. In fact, the unnumbered Joomla 5 plugin must be disabled before upgrading from Joomla 5.4 to Joomla 6.
Which plugin must be enabled before Joomla 6?
Behaviour – Backward Compatibility 6 (compat6) must be installed and enabled on Joomla 5.4. The unnumbered Joomla 5 plugin (compat) must be disabled.
Can I turn off Backward Compatibility 6 after upgrading?
Yes, once every extension and custom integration works natively on Joomla 6. Test it on staging first.
Why did my site break when I disabled it?
An extension, template, or custom plugin still calls a class or asset supplied by the bridge. Re-enable it, inspect the stack trace, and update or refactor the responsible extension.
How do I re-enable it if Administrator is broken?
In #__extensions, find the behaviour plugin with element compat or compat6 and set enabled to 1. Then clear cache and investigate the failing extension.
Can I uninstall the plugin?
No. Treat it as a core plugin and disable it when unused. Deleting it can create file/database mismatches and complicate updates.
Does the plugin make a Joomla 3 extension work on Joomla 6?
No. It only supplies selected compatibility cases from the previous major. A Joomla 3 extension may also depend on removed PHP APIs, manifests, events, libraries, and database behavior.
How do I know an extension is natively compatible?
It installs, updates, and passes its full workflow on the current Joomla major with the relevant compatibility plugin disabled.
Where can Infyways help?
Infyways provides Joomla upgrades, extension development, and support and maintenance for compatibility audits and major-version transitions.
