Blog

Updated 14 October 2026 · By Abhilash Sahoo, Infyways

To check whether your Joomla extensions are compatible with Joomla 6, install the free Migration Scanner from JoomlaX on a staging copy of your site, click Scan site, and read the Dashboard. It inventories every enabled third-party component, module, plugin and template, scans their PHP and XML files, and labels each extension Will not run, Needs review or Ready. For every problem it shows the file, the line number and the replacement code. The scan is read-only and never runs extension code.

In short: Migration Scanner is a free Joomla administrator component for Joomla 4.4, 5 and 6 (PHP 8.1+). It answers one question before you upgrade: which installed extensions will break on my target Joomla version, and where exactly?

Why do you need a Joomla 6 compatibility check?

Most Joomla upgrades do not fail because of Joomla core. They fail because of a third-party extension or template that still uses old Joomla 3-era code, such as JFactory, JText, JRequest or JHtml behaviours.

Joomla keeps many of these old names alive through its backward compatibility plugin (plg_behaviour_compat on Joomla 4/5, plg_behaviour_compat6 on Joomla 6, where the Classes Aliases option is off by default). Everything compat6 covers is scheduled for removal in Joomla 7. For the exact settings per version, see our Joomla backward compatibility plugin guide; for what changed in the release itself, see what’s new in Joomla 6.

So an extension that “works” today may only be working because a compatibility layer is propping it up. A compatibility check tells you which extensions are genuinely ready, which are leaning on the plugin, and which will not run at all.

What is the JoomlaX Migration Scanner?

Migration Scanner is a free, read-only Joomla administrator component that finds legacy PHP APIs and incomplete manifests before you move a site to Joomla 6. It is built and maintained by Infyways under the JoomlaX brand.

	Details
Price	Free (no checkout)
Installs on	Joomla 4.4, 5.x and 6.x
PHP	8.1 or later
Database	MySQL or MariaDB
What it reads	PHP and XML files of enabled, non-core components, modules, plugins and templates
What it skips	Joomla core, disabled extensions, JavaScript, CSS and SQL files (this release)
Changes your files?	No. It does not execute extension PHP or run extension SQL
Target version	Auto (Joomla 6) by default, or choose 4 or 5
Output	Dashboard plan, extension list, per-extension findings, JSON export, printable site report
Version	1.0.0, released 12 October 2026

You can try it first on the live demo.

Who is it for?

• Site owners planning a Joomla 3, 4 or 5 to Joomla 6 upgrade who want to know what will break before they start.
• Agencies that need a printable, shareable report of every blocker on a client site.
• Developers who maintain custom or abandoned extensions and need a file-and-line list of what to rewrite.

What does Migration Scanner detect?

The scanner token-scans PHP and checks XML manifests for a namespace. Each finding is grouped by API, given a severity, and tagged with the compatibility layer it depends on.

Status for each extension

Status	Meaning
Will not run	Uses APIs the compatibility plugin cannot save. Must be rewritten for the target version
Needs review	Still depends on compat6 aliases or similar layers
Ready	Nothing blocking for the chosen target version

Finding types (chips)

• Needs aliases: old class names such as JText or JFactory that only work while Classes Aliases are enabled in compat6.
• Needs legacy classes: code that depends on legacy classes the compatibility plugin still ships.
• Needs asset stubs: references to removed assets that the plugin stubs out.
• Will not run: calls the compatibility plugin cannot rescue.

Severity

Findings are ranked Critical, High, Medium and Low, so you fix what will stop the site first.

Grouped, not duplicated

If JText appears 48 times in one component, you see one group (“JText · Needs compat6 aliases, 48 times”) instead of 48 separate lines. You fix a pattern, not a pile of duplicates. Expand a group to see why it matched and what to put instead.

For the replacement pattern behind each API, see our Joomla Migration Reference. For example, JFactory and application changes, JRequest and Input, HTML helpers (JHtml), JTable and database and deprecated JavaScript (MooTools/jQuery).

How do I install Migration Scanner?

1. Download MigrationScanner_UNZIP.zip free from the Migration Scanner page.
2. Unzip it on your computer. Inside you will find pkg_jxmscanner_*.zip (the file you install) and ReadMe.txt.
3. In the Joomla administrator, go to System > Install > Extensions and upload pkg_jxmscanner_*.zip.
4. Open Components > Migration Scanner to confirm the Dashboard loads.
5. Clear the cache: System > Maintenance > Clear Cache.

You need a Super User or administrator account. You do not need jQuery, a CLI or any extra plugins. Updates use the same steps, and previous scan results stay in the database.

Tip: Do not install the outer _UNZIP file in Joomla. Install the inner pkg_jxmscanner_*.zip.

Still on Joomla 3? How to use the Migration Scanner

The Migration Scanner extension needs Joomla 4.4 or later, so it cannot be installed on a Joomla 3 site. You have two options: scan each extension or template ZIP now with our free online Joomla Migration Scanner, or upgrade a staging copy to Joomla 4.4 and install the extension there. Joomla’s official path is 3.10 → 4.4 → 5.4 → 6; you cannot skip Joomla 4.

Option A: scan ZIP packages online (no upgrade needed)

1. Collect the installation ZIPs of your third-party extensions and template (from the developer, or zip the folders from your site).
2. Drop each ZIP into the online Joomla Migration Scanner. It reads Joomla 3 code, so it works before you upgrade anything.
3. Use the results to decide what to update, replace or rewrite. This is the best route for custom or abandoned extensions that have no newer version.

Option B: upgrade a staging copy, then run the extension

1. Clone the live site to staging. The live site stays on Joomla 3 until the copy works.
2. On the copy, update to the latest Joomla 3.10.
3. Migrate the copy to Joomla 4.4 with the Behaviour – Backward Compatibility plugin enabled.
4. Install Migration Scanner on the copy, scan, and fix what it flags.
5. Continue the copy to Joomla 5.4 and then 6, rescanning at each step, before you touch production.

	Online ZIP scanner	Staging copy + extension
What it checks	One extension or template package at a time	Every enabled third-party extension on the site
What you need	The ZIP files only	A staging copy upgraded to Joomla 4.4+
Best for	Joomla 3 sites, custom or abandoned code, checks before upgrading	A full, site-wide plan once the copy runs Joomla 4.4 or later

For every step of the version jumps, follow our Joomla 3 to 6 upgrade guide. If you would rather have it done for you, see our Joomla upgrade service.

How do I run a Joomla compatibility scan?

Run it on a staging copy of your site. The scan is read-only, but a large site can take several minutes and is easier to review away from production.

1. Open Components > Migration Scanner.
2. Read the host banner. It tells you whether plg_behaviour_compat or plg_behaviour_compat6 is enabled, and whether Classes Aliases, Legacy Classes and Removed asset stubs are on.
3. (Optional) Open Configuration and set the Target Joomla version and Files per step.
4. Click Scan site and wait until the live status pill shows Idle.
5. Use the Dashboard plan, then open an extension marked Will not run.

Configuration: target version and files per step

• Target Joomla version: Auto targets Joomla 6. Pick 4 or 5 if you are staging an upgrade to that version.
• Files per step: how many files each scan step reads (default shown: 40). Lower it if the scan hits PHP max_execution_time on cheap hosting.
• Permissions tab: Super Users can set component permissions.

Save, then run a new scan so the counts match the new target.

How do I read the results?

1. Dashboard: the plan

The Dashboard shows four site-wide counts: All extensions, Will not run, Needs review and Ready. Do this first lists the blockers, and Needs work first is a short table of the worst extensions. From the header you can Scan site, Pause, Export JSON and open the Site report.

2. Extensions: the inventory, worst first

Components > Migration Scanner > Extensions ranks every third-party component, module, plugin and template from worst to best. Filter by status or type, search by name or element (for example com_example), and open a row for its findings. Joomla core never appears here.

3. Findings: file, line and replacement

Open one extension to see All APIs, the alias, legacy and asset-stub layers, and the Will not run items. Each finding names the file path, the line and the replacement. After you edit files, click Scan this extension to re-check just that one; you don’t need to rescan the whole site.

4. Share it

• Export JSON: a machine-readable export that includes bc_layer, bc_param and removed_in for each finding.
• Site report: a printable view for agencies, developers and clients.

How do I fix the issues it finds?

Work from the top of the Dashboard plan:

1. Update first. Check whether the developer has released a Joomla 5/6 version. Updating often clears dozens of findings at once. Rescan afterwards.
2. Replace abandoned extensions. If the developer has stopped updating the extension and it is marked Will not run, look for a maintained alternative.
3. Fix “Needs aliases” items. Replace old names with namespaced classes, for example JText with Joomla\CMS\Language\Text and JFactory::getApplication() with Joomla\CMS\Factory::getApplication(). Our migration reference groups show the before/after code for each API.
4. Rewrite “Will not run” code. These need real changes: namespaced MVC, Web Asset Manager instead of JHtml behaviours, event subscribers, Bootstrap 5 markup in templates. See components and MVC, plugins and events, media and assets and templates and layouts.
5. Rescan the extension until it shows Ready. Then, on staging, test with the Classes Aliases option off so you know the code no longer leans on compat6.

For the full upgrade sequence (backups, PHP version, pre-update check, staging cutover), follow our Joomla 3 to 6 upgrade guide. If something breaks after the upgrade, see common Joomla upgrade issues and fixes.

Migration Scanner vs Joomla’s pre-update check vs manual checks

Joomla’s own pre-update check (System > Update > Joomla, with the update channel set to the next major version) checks required settings. For a Joomla 5 to 6 update it requires the old compatibility plugin to be disabled and Backward Compatibility 6 to be enabled. Its Extensions list relies on what each developer declares, so treat it as a high-level indicator, not proof that the code works.

	Joomla pre-update check	Manual check	Migration Scanner
Looks at extension code	No (relies on developer update data)	Only if you read the code yourself	Yes: PHP tokens and XML manifests
File and line of each problem	No	Slow and error-prone	Yes, with replacement
Shows reliance on compat6 aliases / legacy classes	No	Hard to tell	Yes, per finding
Covers templates	Partly	Yes	Yes (enabled non-core templates)
Site-wide ranked plan	No	No	Yes, worst first
Shareable report	No	Your own notes	JSON + printable report
Cost	Built in	Your time	Free

They work best together: use Migration Scanner to find the code problems, fix them, then run Joomla’s pre-update check before the actual update.

Whole site or single ZIP: which scanner should I use?

We also run a browser-based Joomla Migration Scanner that checks one package. You drop a single extension or template ZIP into it, and it is useful before you install anything or when you only have the package. The JoomlaX extension scans the installed site: every enabled third-party extension at once, with a Dashboard plan and per-extension rescans. Use the online tool for one package, and the extension for a whole site.

DIY or hire help?

Do it yourself if the scan shows mostly Ready or Needs review extensions that have updates available, and you are comfortable editing PHP on staging.

Get help if you have Will not run extensions that are custom-built or abandoned, a Joomla 3 template, or no developer time. Migration Scanner has a Paid support tab for this. It is optional, and the scanner stays free.

1. Open Components > Migration Scanner > Paid support, or click Ask for paid support on the Dashboard or an extension report.
2. Name the extension and your target Joomla version.
3. Infyways quotes a rewrite. You only pay if you want the fix.

For a full site upgrade, done on staging with your sign-off before production, see our Joomla upgrade service and Joomla extension upgrade.

Troubleshooting

• Scan never finishes: lower Files per step, check PHP max_execution_time on staging, and start again.
• Old results showing: the Dashboard uses the newest scan. Run Scan site again after installing or updating extensions.
• An extension is missing: only enabled third-party extensions are inventoried. Core and disabled items are skipped.
• JavaScript files not listed: this release reads PHP and XML only.
• Menu still says Preferences: clear the cache and open Configuration from the component submenu or the cog.

If a result does not match what you see in the files, open a ticket at support.joomlax.com. Include your Joomla and PHP versions, the extension element, and a JSON export or a screenshot of the finding.

Frequently asked questions

How do I check if a Joomla extension is compatible with Joomla 6?

Install the free Migration Scanner on a staging copy, leave the target on Auto (Joomla 6) and click Scan site. Each enabled third-party extension is marked Will not run, Needs review or Ready, with file-and-line findings. Also check the developer’s site for a Joomla 6 release.

Is Migration Scanner free?

Yes. The scanner is free to download and use. Paid support is optional and only applies if you want Infyways to rewrite an extension.

Which Joomla versions does it support?

It installs on Joomla 4.4, 5 and 6 and needs PHP 8.1 or later. You can target Joomla 4, 5 or 6 in Configuration.

Can I use the Migration Scanner on Joomla 3?

Not the extension: it installs on Joomla 4.4 or later. On a Joomla 3 site, scan each extension or template ZIP with our free online Joomla Migration Scanner, or upgrade a staging copy to Joomla 4.4 and install the extension there.

Can I upgrade from Joomla 3 straight to Joomla 6?

No. Joomla’s official path is 3.10 → 4.4 → 5.4 → 6. Each major upgrade requires the latest release of the previous version, so you cannot skip Joomla 4 or 5. Do every step on a staging copy first.

How do I check Joomla 3 extensions for Joomla 6 compatibility?

Upload each extension or template ZIP to the free online Joomla Migration Scanner, which reads Joomla 3 code. For a site-wide check, upgrade a staging copy to Joomla 4.4, install the Migration Scanner extension, and set the target to Joomla 6.

Does it change or break my extensions?

No. The scan is read-only. It does not execute extension PHP or run extension SQL, and it does not need write access to extension files.

Should I run it on a live site?

Run it on a staging copy. It is safe to run, but a large site can take several minutes, and the results are easier to review off production.

What files does it scan?

PHP and XML in enabled, non-core components, modules, plugins and templates. Joomla core, disabled extensions, JavaScript, CSS and SQL files are not scanned in this release.

What does “Needs compat6 aliases” mean?

The extension uses old class names (such as JText or JFactory) that only resolve while the Behaviour – Backward Compatibility 6 plugin has Classes Aliases turned on. It may work today, but compat6 is scheduled for removal in Joomla 7, so the code should be updated.

Download Migration Scanner free

Find out what will break before you upgrade, not after. Download Migration Scanner free from JoomlaX, read the documentation, and run your first Joomla 6 compatibility check on staging today.

If the scan shows work you would rather not do yourself, talk to our Joomla upgrade team.

Joomla custom fields are not showing when a display gate is closed: Automatic Display is off or pointed at a slot the view never renders, the field is unpublished or not assigned to the article’s category, Access hides it, an override never prints the fields block, or cache is serving a page from before the field existed. Values can sit in the article editor and still never reach the public HTML. This page is troubleshooting only. The feature how-to is Joomla custom fields.

If you have not created the field yet, stop and use that how-to. If the Fields tab has a value and the frontend does not, stay here.

Admin can show a value while the public view never fires After Title, After Display, or your override. Treat display as a separate pipeline.

What you will learn

• How to prove the value exists before you touch templates
• What After Title, Before Display Content, After Display Content, and Do not automatically display actually inject
• Why Assigned Categories All skips Uncategorised
• How unpublished fields, ACL, and Display When Read-Only hide output
• How article context vs category context sends you to the wrong Fields list
• How a layout override or CSS can remove fields that Joomla did render
• Why cache makes a fixed field look broken for hours

Official parameters: J5.x Adding custom fields, parameters and the user manual Field parameters. Events: Content events (programmers).

Split the problem before you edit PHP

Symptom	What it usually is	What it is not
Field missing on the article edit form	Category assignment, unpublished field, wrong context (Category vs Article), plugin off	Automatic Display
Value on the form, missing on the public article	Automatic Display, ACL, override, cache	“Joomla deleted the field”
Shows on the article, missing on the blog	Blog layouts often do not run the same display events the same way	Category assignment alone
Shows for Super Users, not for guests	Field Access or Display When Read-Only	Template chrome
Shows in HTML, not on screen	CSS, or label hidden and value empty-looking	Unpublished

Do not start in html/com_content/article/default.php. Start in Content → Fields.

Step 1: Confirm the value and the plugins

1. Content → Articles. Open the article. Open the field group tab (or Fields). Confirm the value is saved. If the input is missing in admin, this is assignment or context, not frontend display. Jump to Step 3 and Step 5.
2. System → Plugins. Search Fields. System – Fields must be enabled. Field type plugins (Fields - Text, Fields - Calendar, and the type you used) must be enabled. If you disable Fields - Media, media fields stop.
3. Content → Articles → Options → Integration. Custom Fields must be enabled for articles. Contacts and Users have their own Options.

If editors cannot type a value, that can be Edit Custom Field Value (core.edit.value) inherited as Not Allowed. Grant it on Content → Articles → Options → Permissions for the right group, or on the field. That is an admin ACL issue. Super Users still see values. Guests never will if Access on the field is Special.

Step 2: Set Automatic Display (After Title, After Display, or none)

On Content → Fields, open the field. Find Automatic Display:

Setting	Event	Where it usually appears
After Title	onContentAfterTitle	Under the title, before intro
Before Display Content	onContentBeforeDisplay	Above the body
After Display Content	onContentAfterDisplay	Below the body
Do not automatically display	none of the above	Nowhere, until {field ID} or an override prints it

Do not automatically display is the number one “not showing” after a careful setup. It is also the correct choice when you print fields in a child template layout. If you expected automatic output and left this on, change it to After Title or After Display Content, save, clear cache.

A whole group renders as one block in field order. If one field in the group is unpublished, the others can still show.

{field 12} in the article body needs the field id, not the name. Wrong id prints nothing useful. The Content – Fields plugin (or the editor Field button) inserts the syntax. If you type {field price} Joomla will not guess.

Blog (category) views and some third-party layouts do not call the same events, or they call them in a list context where you chose not to show fields. If the single article is fine and the blog is empty, Automatic Display is working. The blog layout is not a full article view. Use an override on html/com_content/category/ or accept fields only on the article.

Step 3: Fix category assignment (All does not mean Uncategorised)

The docs are explicit: the default All for Assigned Categories does not include Uncategorised.

If the article is in Uncategorised, the field can be absent from the editor and from the frontend. Assign Uncategorised explicitly, or move the article into a category you did tick.

Other assignment misses:

• You ticked “News” but the article is in “News / 2026” as a child. Child categories are not automatic. Tick the child, or tick every category that should show the field.
• You assigned the field to one category, then moved the article. The value may still exist in the database. The form and display rules follow the current category.
• New articles: the Fields tab stays empty until a category is chosen. That is normal. Joomla waits so it can apply assignment.

After a K2-style migration, Uncategorised is common. The how-to covers the happy path: Joomla custom fields.

Step 4: Unpublished, Access, and read-only display

On the field:

• Status must be Published. Unpublished fields are hidden in the editor for normal users and do not render on the site. Archived is the same idea with a different filter in Fields.
• Access (Public, Guest, Registered, Special) applies to viewing the value on the frontend. A field set to Registered will not show to a guest. That is not a template bug.
• Display When Read-Only: if the visitor cannot access the value, Yes still shows it, No hides it. Inherit follows the parent. A guest hitting a Registered field with Display When Read-Only = No sees nothing.
• Language on the field: same trap as modules. A field set to French will not attach to an English article the way you expect.

ACL on the article can also stop the whole page. If the article is not viewable, fields are a side issue. Test logged out in a private window.

Step 5: Article fields vs category fields vs contacts

Content → Fields has a context switch: Article, Category, Contact, User (wording depends on what is installed).

If you created the field in Category context, it lives on the category edit form, not on the article. The article page will not print it as an article field. You will hunt Automatic Display forever.

If you created it under Contacts, articles will never show it.

Open Fields, set the filter to Article, and confirm your field is in that list. Title collisions across contexts are possible. Use the id in the URL when you edit.

Step 6: Overrides and CSS that hide fields

Automatic Display injects HTML when com_content (or contact) dispatches those content events in the view. A custom article layout that never triggers them will never print automatic fields.

Typical override failures:

• html/com_content/article/default.php copied from an old template or a page builder, then stripped to $this->item->text only. Events never run. Fields vanish even with After Title set.
• A html/layouts/joomla/content/ override that removed the after-title output.
• A html/layouts/com_fields/field/render.php (or field render) override that returns empty, or wraps output in a class your CSS sets to display: none.
• Alternative layout on the article (a different default_foo.php) that you never updated for fields.

Fix path: put overrides in a child, not in Cassiopeia core. Customize Joomla without editing core. If the field type uses a plugin tmpl, plugin overrides apply. Diff your default.php against the core file in components/com_content/tmpl/article/default.php. If core still calls the events and your copy does not, restore those calls.

CSS: inspect the public page. Classes like field-entry, field-label, field-value (exact names depend on layout) may be in the HTML. If they are, Joomla showed the field. Your user.css or the template hid it. If they are not in the HTML, you are still on Steps 2 to 5, not CSS.

Empty values: Automatic Display typically prints nothing useful when the value is empty. A required field that was never saved on old articles will look like “not showing.” Open the article and save a value.

Step 7: Cache, and then a frontend proof

After every field or override change:

1. System → Maintenance → Clear Cache.
2. If System – Page Cache is enabled, clear that too, or disable it on staging while you test.
3. CDN / host cache: purge the article URL.
4. Hard-refresh the public article logged out.

Joomla can cache the article HTML from before Automatic Display was set. You will swear the setting does nothing. The cached page is the old page.

Conservative caching of modules does not usually store article field HTML, but page cache does.

If the editor has no input, fix assignment and context. If the editor has a value, fix Automatic Display, Access, override, then cache.

Label hidden, empty value, and unpublished groups

Automatic Display can “work” and still look like a blank article.

• Show Label is off and the value is a short code or a boolean that CSS does not style. Inspect the HTML. If a field-value (or the layout’s equivalent) is there, the field showed. You are in CSS or design, not in Fields.
• The article never saved a value. Old articles created before the field existed stay empty until you open and save them. A default on the field applies to new items more reliably than to a thousand legacy rows.
• Field groups have their own published state. An unpublished group can hide the tab in the editor, which looks like the field “vanished.” Publish the group, then the field.

Media and calendar fields fail in a specific way: the value is a path or a date Joomla cannot render in that layout. Open the article, confirm the media picker still points at a file that exists. After a migration, broken paths are common. That is data, not Automatic Display.

If you use {field ID} and the id is from a different context (you copied the id from a contact field onto an article), the shortcode will not fill. Use the Article fields list id.

Blog vs article, and third-party views

Single article (com_content article view) is where After Title / After Display are designed to run.

Category blog, featured, and tag views may show intro text only. Fields will not appear in the list unless the layout prints them. That is expected. Do not “fix” Automatic Display for a blog card. Override the blog item layout in a child, or keep fields on the full article.

Third-party components that are not com_content do not gain article fields by magic. They need their own field context or their own templating. A directory extension is not “Joomla custom fields not showing.” It is a different component.

Key takeaways

1. Troubleshooting starts in Content → Fields and the article form, not in random PHP.
2. Do not automatically display means the public page stays empty unless you use {field ID} or an override.
3. After Title and After Display Content only work in views that fire those content events.
4. Assigned Categories All skips Uncategorised. Tick it or move the article.
5. Unpublished fields, non-Public Access, and Display When Read-Only hide frontend output on purpose.
6. A field created in Category or Contact context will never show as an article field.
7. Article default.php overrides that drop content events remove automatic fields. Keep overrides in a child and diff against core.
8. Clear page cache after you change display. Old HTML is the most convincing fake bug.

Create and assign fields using the companion article: Joomla custom fields. If a production template override is swallowing fields after an update, Joomla support and maintenance.

Related Joomla troubleshooting

• Customize without editing core
• Extension installed but not working
• Template override not working

Frequently asked questions

Why are my Joomla custom fields not showing on the article?

Automatic Display is often Do not automatically display, the article category is not assigned (Uncategorised is the usual miss), Access is not Public, or an article override never fires the content events. Confirm the value in the editor first.

What is the difference between After Title and After Display?

After Title injects on onContentAfterTitle (under the title). After Display Content injects on onContentAfterDisplay (after the body). Before Display Content sits above the body. None of these run if you choose Do not automatically display.

Why does All categories not include Uncategorised?

That is core behaviour, documented on the custom fields parameters page. Assign Uncategorised explicitly or move the article.

Do custom fields show on the category blog?

Not unless that layout prints them. Automatic Display is built around item views that dispatch the content events. Use a category override if list cards must show a field.

Can an unpublished field still hold data?

The value can remain in the database. Unpublished means the field is hidden from normal editing and from frontend display. Publish it to use it again.

How do I show a field only in an override?

Set Automatic Display to Do not automatically display, then print the field in a child template layout. If you leave After Title on, you will get automatic output plus your override.

Could cache hide a field I just added?

Yes. Page cache and CDNs store the article HTML. Clear Joomla cache and the URL at the edge, then test logged out.

Short answer: If your Joomla site sells products or services to consumers in the EU, such as an online shop, a booking system or a consumer banking portal, the European Accessibility Act (EAA) has applied to it since 28 June 2025, unless you are a microenterprise providing services (fewer than 10 staff and no more than €2 million in annual turnover or balance sheet total). In practice, you meet the EAA by following the harmonised standard EN 301 549. Its current legal version (V3.2.1) points to WCAG 2.1 Level AA, and the new V4.1.1, published in September 2026, moves to WCAG 2.2 AA. Joomla 5 and 6 give you a solid start, with an accessible default template and a built-in content checker. But an independent 2026 audit still found issues in core, and most real-world failures come from templates, extensions and content. So you need to audit, fix at the source and publish an accessibility statement. An overlay widget on its own won’t make you compliant.

In this guide: who the EAA covers, which WCAG version to target, what Joomla core already does (and where it falls short), a practical checklist with native fixes, how to handle the problems core can’t, and an FAQ. This article is general information, not legal advice. Check your own obligations with a qualified adviser.

What Is the European Accessibility Act?

The European Accessibility Act is >Directive (EU) 2019/882. It sets common accessibility requirements for certain products and services sold in the EU. Each member state wrote it into national law. Germany did this with the Barrierefreiheitsstärkungsgesetz (BFSG), and Italy, France, the Netherlands and Poland have their own transposing acts. That’s why enforcement and penalties differ from country to country.

For website owners, these are the parts that matter:

• Since 28 June 2025 it applies to services provided to consumers. That includes e-commerce services, consumer banking services, e-books, electronic communications, access to audiovisual media, and websites, apps and e-ticketing for passenger transport (Article 2).
• The directive defines e-commerce services broadly: services provided at a distance, through websites and mobile apps, at a consumer’s request, with a view to concluding a consumer contract. If visitors can buy, book or subscribe on your Joomla site, assume you’re in scope.
• Microenterprises providing services are exempt. That means fewer than 10 employees and an annual turnover or balance sheet total of no more than €2 million (Article 2(23) and Article 4(5)). Microenterprises dealing in products get lighter rules but aren’t exempt.
• Some content is excluded. That includes pre-recorded audio and video and office files (PDF, DOCX) published before 28 June 2025, archived content that hasn’t been edited since that date, and third-party content you don’t fund or control (Article 2(4)).
• Location doesn’t matter. A US, UK, Swiss, Australian or Canadian company that sells to consumers in the EU >must comply for those EU services.
• Service providers must explain how the service meets the requirements and make that information public in an accessible format (Article 13 and Annex V). In practice, that’s an accessibility statement.

Does the EAA apply to my Joomla site? A quick test

Your Joomla site…	EAA likely applies?
Runs a shop (VirtueMart, HikaShop, J2Commerce, etc.) selling to EU consumers	Yes (e-commerce service)
Takes bookings or paid subscriptions from EU consumers online	Very likely (contract concluded online)
Is a brochure or blog site with a contact form only	Usually not directly, but see the other laws below
Is a B2B portal that only sells to businesses	Usually not (the EAA covers consumers)
Belongs to a business with fewer than 10 staff and ≤ €2M turnover/balance sheet	Exempt for services, but still encouraged
Belongs to an EU public-sector body	Covered by the Web Accessibility Directive, which uses the same EN 301 549 standard

Even when the EAA doesn’t apply, accessibility rules elsewhere often do. Examples include the UK Equality Act 2010, the US ADA, Australia’s Disability Discrimination Act and Ontario’s AODA. They all point to WCAG in one form or another, so a single WCAG 2.2 AA approach covers every market.

WCAG 2.1 or WCAG 2.2: Which Should Joomla Sites Target?

The EAA states its requirements in functional terms. A service that conforms to a harmonised standard cited in the EU Official Journal is presumed to conform (Article 15). That standard is EN 301 549:

• EN 301 549 V3.2.1 (2021) is still the legal reference today. Its web requirements match WCAG 2.1 Level AA.
• EN 301 549 V4.1.1 was adopted on 24 August 2026 and published in September 2026. It >moves the baseline to WCAG 2.2 Level AA, adds an annex mapping the standard to the EAA, and adds requirements about respecting users’ accessibility preferences. It only becomes the legal reference once the Commission cites it in the Official Journal. >The expected date varies by source, with late 2026 being the usual estimate.

Our recommendation: build and audit against WCAG 2.2 AA now. WCAG 2.2 is backwards compatible with 2.1, so meeting 2.2 AA also meets 2.1 AA. And any redesign you start today will go live after the new standard is cited.

What WCAG 2.2 adds (Level A and AA)

According to >W3C’s “What’s New in WCAG 2.2”, these are the six new A/AA success criteria. 4.1.1 Parsing has been removed.

Criterion	Level	What it means on a Joomla site
2.4.11 Focus Not Obscured (Minimum)	AA	Sticky headers, cookie banners and chat widgets mustn’t completely hide the element that has keyboard focus
2.5.7 Dragging Movements	AA	Sliders, carousels, sortable lists and map pins need a non-drag alternative (buttons, arrows)
2.5.8 Target Size (Minimum)	AA	Clickable targets must be at least 24×24 CSS px or well spaced. Watch social icons, pagination and tag links
3.2.6 Consistent Help	A	Help options (contact link, phone, chat) appear in the same place on every page
3.3.7 Redundant Entry	A	Multi-step forms and checkouts shouldn’t ask for the same information twice
3.3.8 Accessible Authentication (Minimum)	AA	Login and registration can’t depend on a cognitive test. Allow paste and password managers, and offer alternatives to puzzle CAPTCHAs

What Joomla 5 and 6 Already Give You

Joomla has taken accessibility seriously since version 4. Here’s what core gives you:

• Cassiopeia, the default site template. The >Joomla documentation describes it as “an excellent general purpose accessible and responsive template”. It uses semantic HTML5 landmarks (header, nav, main, footer). The docs also warn that colours you choose must still have enough contrast.
• Atum, the administrator template. Your editors work in Atum, and it includes accessibility settings. The audit below found issues there too, which matters if staff with disabilities manage content.
• The Joomla Accessibility Checker (jooa11y). This core system plugin has been >included since Joomla 4.1. After you save an article, an Accessibility Check button runs more than 50 tests: missing or weak alt text, skipped or empty headings, unclear link text, missing captions, PDF links and more. Optional checks cover contrast, form labels and readability. You’ll find it under System → Plugins → “System – Joomla Accessibility Checker”. As the >Joomla manual puts it, it identifies problems but doesn’t fix them.
• Language attributes are set from the content language, and multilingual sites can mark up each language.
• Alt-text fields in core media (intro and full-text images) and a “No description” option for decorative images.

Where core still falls short: the 2026 audit

In 2026 the Joomla project commissioned an independent WCAG 2.2 AA audit by Axess Lab. It covered Atum, Cassiopeia, login and MFA, the Media Manager, the installer and update process, and forms. According to the >Joomla Community Magazine summary and the >published report, it found 42 issues. The ones that matter for a typical public website include:

• No skip link in Cassiopeia by default. Keyboard-only users have to tab through the whole menu on every page.
• Low contrast for focus states and the current menu item (below 3:1).
• Tag links without context for screen-reader users.
• Undefined focus styles in Atum’s navigation, plus Media Manager issues with roles, states and keyboard use.

The good news is that the Joomla project is publishing this openly and working through the fixes. Until those fixes ship in a release you’re running, these gaps are yours to close.

Keep in mind that core is rarely the main problem. On most Joomla sites we audit, the failures come from third-party templates, page builders, sliders, popups, cookie banners, forms and years of content.

The Joomla Accessibility Checklist (Native Fixes First)

Work through these in order. Each item says how to fix it with what Joomla already offers.

1. Audit before you change anything

• Turn on the jooa11y plugin and check your most-visited articles.
• Run a free automated scan (for example >WAVE or axe DevTools) on your home page, a category page, an article, a form page and your checkout or booking flow.
• Test by keyboard: unplug the mouse and use Tab, Shift+Tab, Enter and Escape through the menu, forms, popups and checkout.
• Do a quick screen-reader check (NVDA on Windows, VoiceOver on Mac or iOS).
• Automated tools only catch part of the issues. W3C’s >Evaluating Web Accessibility overview explains why manual checks are essential.

2. Template: skip link, focus and contrast

• Add a “Skip to main content” link in a child template of Cassiopeia (or your own template), as the first focusable element and pointing to <main id="main">.
• Make focus visible. Add a clear :focus-visible outline in user.css with at least 3:1 contrast against its background.
• Check colour contrast for body text (4.5:1), large text (3:1) and UI parts such as buttons, form borders and the current menu indicator (3:1). Use the >WebAIM Contrast Checker.
• Make sure sticky headers don’t cover focused elements (WCAG 2.2 2.4.11). Add scroll-padding-top equal to the header height.

3. Images and media

• Give every meaningful image real alt text that describes its purpose, not “image of…”. Mark decorative images as decorative.
• Linked images need alt text that describes where the link goes.
• Videos need captions. Audio needs a transcript.
• Add a title attribute to every YouTube, Vimeo or map iframe.

4. Headings and content structure

• One H1 per page (usually the article title), then H2 and H3 in order with no skipped levels.
• Use real lists, not lines starting with dashes. Don’t use bold paragraphs as headings.
• Write link text that makes sense out of context. Avoid repeated “Read more” links pointing to different pages. Joomla’s “Read more” layout can include the article title in a template override.
• Warn users when a link opens in a new tab or points to a PDF.

5. Forms, login and checkout

• Every input needs a visible <label>. A placeholder isn’t a label.
• Error messages must say what went wrong and how to fix it, and they must be announced to screen readers.
• Mark required fields in text, not only with colour or an asterisk.
• Allow paste into password fields and don’t block password managers (WCAG 2.2 3.3.8). Offer a CAPTCHA alternative.
• In checkout, don’t ask for the same address twice. Offer “same as billing” (3.3.7).

6. Menus, sliders, popups and cookie banners

• Drop-down menus must open with the keyboard and expose aria-expanded.
• Carousels need pause controls and keyboard and button navigation, not drag-only (2.5.7). Avoid auto-rotating hero sliders.
• Popups and modals must move focus inside, keep focus there, close with Escape and return focus when closed.
• Cookie banners are a common blocker. They must be keyboard-operable, readable by screen readers and must not hide focused content.

7. Documents

• PDFs published or edited since 28 June 2025 should be accessible (tagged, with reading order and alt text), or have an HTML alternative.

8. Publish an accessibility statement

• Create a Joomla article (or menu item) called Accessibility and link it in the footer. Say which standard you target (EN 301 549 / WCAG 2.2 AA), known limitations, the date of your last review, and how users can report problems and get content in another format. The EU’s >model accessibility statement for public-sector sites is a useful template, and Annex V of the EAA lists what service providers must explain.

9. Keep it compliant

• Make accessibility part of your publishing workflow. Editors should run jooa11y before they publish.
• Re-test after every template, extension or Joomla update.
• Keep a short log of what you tested, when and what you fixed. If a regulator or customer asks, it’s your evidence.

Why an Overlay Widget Alone Won’t Make You Compliant

“One-line” accessibility overlays promise instant compliance. Regulators don’t accept that claim. In January 2025 the US Federal Trade Commission ordered accessiBe to pay $1 million over claims that its AI widget could make any website WCAG-compliant. The >final order bars it from making such claims without evidence.

The reason is simple. WCAG is about the HTML, structure and behaviour of your site. If your form has no labels, your slider traps focus or your checkout repeats fields, a floating toolbar doesn’t change that. Fixes have to happen in the page itself.

A visitor toolbar can still help people. Text size, contrast, dyslexia-friendly fonts and read-aloud tools are genuinely useful to some visitors. Just treat it as an extra on top of a site that’s already accessible, not as a replacement for one.

Fixing What Core Can’t: A Practical Path

Template overrides and careful editing will get you a long way. But on a site with hundreds of articles, many extensions and many editors, fixing everything by hand is slow and easy to break on the next update. That’s the gap we built two tools for at JoomlaX:

• >Easy WCAG fixes common accessibility gaps in the HTML Joomla sends to the browser. It adds missing alt and iframe titles, names icon-only links and buttons, sets the page lang, labels unlabelled inputs, adds a skip link and new-window warnings. It then reports what still needs a human. Your articles in the database stay untouched, and it runs on your own server with no overlay script and no third-party CDN. It’s deliberately honest: it doesn’t claim WCAG AA certification, because no plugin can.
• >Easy Accessibility is a self-hosted visitor toolbar with text size, contrast, Read Mode, a dyslexia-friendly font, on-device read-aloud and more. You can sort or remove any tool. Use it alongside source-level fixes, as described above.

Both run on Joomla 4, 5 and 6.

If you’d rather have it done for you, our Joomla development team runs accessibility audits against WCAG 2.2 AA, fixes templates and overrides, cleans up content and writes your accessibility statement. We often combine this with a Joomla 6 upgrade or performance optimisation, because accessible, well-structured pages also tend to load faster and rank better.

Accessibility Rules Beyond the EU (Quick Reference)

Market	Main rule	Technical benchmark
EU (DE, IT, NL, FR, PL…)	EAA (private, consumer services); Web Accessibility Directive (public sector)	EN 301 549 → WCAG 2.1 AA now, 2.2 AA next
United States	ADA. For state and local government, the >DOJ Title II rule requires WCAG 2.1 AA (compliance dates now April 2027 and April 2028)	WCAG 2.1 AA (Title II); WCAG is widely used in private-sector cases
United Kingdom	Equality Act 2010; public sector accessibility regulations	WCAG 2.2 AA is the >UK government benchmark for the public sector
Canada	Accessible Canada Act (federal); AODA (Ontario)	WCAG 2.0 AA under AODA; EN 301 549 referenced federally
Australia	Disability Discrimination Act 1992	WCAG is the >accepted reference
Switzerland	Disability Discrimination Act (BehiG) at home; EAA applies when selling to EU consumers	eCH-0059 / WCAG

Because nearly all of these point to WCAG, one WCAG 2.2 AA programme covers every market you sell in.

Frequently Asked Questions

Is Joomla WCAG compliant out of the box?

Not fully, and no CMS is. Joomla 5 and 6 ship an accessible default template (Cassiopeia) and a built-in checker (jooa11y). But the independent 2026 WCAG 2.2 AA audit found 42 issues across core, including a missing skip link and low-contrast focus states in Cassiopeia. Compliance also depends on your template, extensions and content.

When did the European Accessibility Act start applying to websites?

On 28 June 2025. It covers e-commerce and other consumer services provided after that date. Some existing content is excluded, such as pre-recorded media and office files published before that date, and archived content that hasn’t changed since.

Does the EAA apply to small businesses?

Microenterprises providing services, meaning fewer than 10 employees and no more than €2 million in annual turnover or balance sheet total, are exempt from the service requirements. Small and medium-sized businesses above that threshold aren’t exempt.

Does the EAA apply to companies outside the EU?

Yes, if they provide covered services, such as online sales, to consumers in the EU. Where your company is based doesn’t matter.

Should I aim for WCAG 2.1 or WCAG 2.2?

Aim for WCAG 2.2 AA. EN 301 549 V3.2.1 (WCAG 2.1 AA) is still the legal reference, but V4.1.1, published in September 2026, moves to WCAG 2.2 AA. And meeting 2.2 AA also meets 2.1 AA.

Will an accessibility plugin or overlay make my Joomla site compliant?

Not on its own. Plugins that fix the HTML at the source and report what’s left can save a lot of time, but a person still has to test keyboard use, forms and content. Toolbar-only overlays don’t fix the underlying code, and the US FTC has fined a vendor for claiming they do.

How do I check my Joomla site’s accessibility for free?

Turn on the core “System – Joomla Accessibility Checker” plugin, run WAVE or axe on key templates, then test every page type by keyboard and with a screen reader. The automated tools find a share of the issues, and manual testing finds the rest.

Do I need an accessibility statement on my Joomla site?

Under the EAA, service providers must publicly explain how their service meets the accessibility requirements, and an accessibility statement is the standard way to do that. Public-sector sites in the EU must publish one under the Web Accessibility Directive.

---

Disclaimer: This article is general information about accessibility standards as of October 2026. It is not legal advice. National implementations of the EAA differ, so check your obligations with a qualified adviser in each market where you operate.

Short answer: Joomla 4, 5 and 6 have no built-in tool to bulk import or export users. Your options are a database import or export through phpMyAdmin, which works but skips Joomla’s own save logic, or a user import/export extension such as JoomlaX User Import Export, which handles CSV, Excel, JSON and XML files with field mapping, validation and password options. This guide walks through both, step by step.

In this guide: what Joomla can and can’t do natively, the manual phpMyAdmin method and its risks, step-by-step import and export with an extension, a ready-to-use CSV template, troubleshooting, best practices and an FAQ.

Does Joomla Have a Built-in User Import or Export?

No. In Joomla 4, 5 and 6, Users: Manage lets you create, edit, block, activate, delete and batch-process existing users (for example, adding them to a group), but there is no Import or Export button. You can’t upload a CSV of new accounts, and you can’t download your user list as a spreadsheet.

The closest core feature is the Privacy component, which can export the data held about a single user in response to a data request. That’s built for privacy compliance, one person at a time, not for bulk migration or reporting.

That leaves two practical routes:

• Manual database work with phpMyAdmin or another MySQL tool.
• A dedicated extension that imports and exports from the Joomla administrator.

Need	Joomla core	phpMyAdmin / SQL	User import/export extension
Bulk import new users from CSV or Excel	No	Yes, if you match the table structure yourself	Yes
Export users to a spreadsheet	No	Yes, raw table data	Yes, with chosen fields and filters
Map your own column names	No	No, columns must match the table	Yes
Assign user groups	One user at a time, or batch existing users	Separate mapping table	Yes, from a column or a default group
Custom fields and profile data	Edit per user	Separate tables, manual joins	Supported
Validation before import	N/A	None	Yes
Runs Joomla user plugins on save	N/A	No	Depends on the extension
Skill level	N/A	Comfortable with databases	Joomla administrator

Option 1: Import and Export Users With phpMyAdmin

If you’re comfortable with databases, you can move users directly between Joomla’s tables. The Joomla documentation page on bulk uploading users describes this approach. It was written for older Joomla versions, so treat it as a concept, not a recipe for Joomla 5 or 6.

Which tables hold Joomla users?

Your table prefix will differ from the #__ placeholder below:

• #__users: core account data such as name, username, email, password hash, block status and registration date.
• #__user_usergroup_map: one row per user and group pair (user_id, group_id).
• #__user_profiles: profile plugin data such as address and phone, if the User – Profile plugin is enabled.
• #__fields_values: values of user custom fields.

Exporting with phpMyAdmin

1. Open phpMyAdmin from your hosting control panel and select the Joomla database.
2. Select the #__users table and open the Export tab.
3. Choose CSV (or SQL if you’re moving to another database) and download the file.
4. Repeat for #__user_usergroup_map if you need group memberships, then join the data in a spreadsheet.

Importing with phpMyAdmin

1. Take a full backup of the site and database first.
2. Prepare a CSV whose columns exactly match #__users, with unique usernames and emails.
3. Import it into #__users using phpMyAdmin’s Import tab.
4. Add matching rows to #__user_usergroup_map so every user belongs to at least one group (usually Registered). Without a group, the account won’t behave like a normal user.
5. Log in as a test user to confirm the account works.

The catches with the database method

• Passwords. Joomla stores password hashes, not passwords. You can’t import plain-text passwords into #__users. Either copy hashes from a compatible Joomla source or leave them unusable and have users reset their password.
• No validation. Nothing checks for duplicate emails, invalid addresses or missing fields before rows go in.
• Joomla plugins don’t run. Writing to the database skips Joomla’s user save events, so integrations that react to new users, such as newsletter subscriptions or welcome emails, never fire.
• Groups, profiles and custom fields live elsewhere. You have to build and import each related table yourself and keep the user IDs aligned.
• Easy to break. One wrong column on a live site can lock out users. Always test on a staging copy.

The database route is fine for a one-off copy between two Joomla sites you control. For spreadsheets from clients, repeated imports or anything with custom fields, an extension is safer and faster.

Option 2: Import and Export Users With JoomlaX User Import Export

JoomlaX User Import Export is a Joomla component (we build it at Infyways) that brings import, export, field mapping, validation, password handling, saved templates and operation logs into the Joomla administrator. The steps below follow the official documentation.

Task	Supported formats
Export users	CSV, Excel (XLSX), JSON, XML, SQL
Import users	CSV, Excel (XLSX/XLS), JSON, XML

Requirements and installation

• Joomla 5.x or 6.x
• PHP 8.1 or higher (8.2+ recommended)
• MySQL 5.7+ or MariaDB 10.3+
• Excel (XLSX) files need the PhpSpreadsheet library. Without it, CSV still works fully.

Install it like any Joomla extension: go to System > Install > Extensions, upload com_userimportexport.zip, then open Components > User Import Export. The dashboard shows user statistics, quick Import and Export buttons, and recent operations. Before your first import, open Options to review password handling, log retention and access permissions.

How to Import Users Into Joomla From CSV or Excel

Step 1: Prepare your import file

Put column headers in the first row and save the file as UTF-8 so accented characters survive. At minimum, each row needs a username and an email, and a name is recommended. On the Import page you can click Download Sample Template to get a pre-formatted CSV. See the template section below for the full column list.

Step 2: Upload the file

Go to Components > User Import Export > Import and drag your CSV, XLSX, XLS, JSON or XML file onto the upload area, or click to browse. CSV delimiters (comma, semicolon, tab or pipe) are detected automatically, which helps with spreadsheets saved in European regional settings.

Step 3: Map your columns to Joomla fields

Click Auto-Detect to map columns by their header names. Common variations are recognized, so email, e-mail and mail all map to Email. Then check each dropdown and fix any column that should go somewhere else. You can map to:

• Core fields such as username, email, name and block status
• User groups
• Profile fields, using profile_ columns such as profile_phone or profile_city
• Joomla user custom fields that store a single value (text, list, radio and similar), listed under “Custom Fields” in the mapping dropdown

Step 4: Choose the import mode

This decides what happens when a row matches an existing account. Existing users are matched by email or username.

Import mode	What it does	Use it when
Add New Only	Creates new users and skips existing ones	Onboarding a fresh list without touching current accounts
Update Existing Only	Updates matching users and skips new ones	Correcting emails, groups or profile data in bulk
Add and Update	Creates new users and updates existing ones	Syncing a master spreadsheet with your site

You can also set a Default User Group for rows that don’t have a groups column.

Step 5: Decide how passwords are handled

• Generate Random: creates a secure password for each new user. Leaving the password cell empty also triggers this.
• Import from File: plain-text passwords in the file are hashed on import. Pre-hashed bcrypt values, for example from another Joomla site, are detected and kept as they are.
• Require Reset: forces users to set a new password on their first login.

There’s also a Send email option. When it’s on, each new user gets one welcome email with their username and either the generated password or a link to set one. When it’s off, imported users get no email.

Step 6: Validate before you import

Click Validate. The component checks email formats, username rules, required fields, duplicates inside the file and users that already exist on the site, and lists row-by-row errors and warnings. Fix problems in your source file and upload it again. It’s much easier than cleaning up bad accounts later.

Step 7: Run the import and review the log

Click Import and watch the progress. The result shows how many users were created, updated and skipped. If rows were skipped or failed, open the Logs view, click Report to see each row and the reason (for example, “User already exists (add-only mode)”), and download the report as a CSV. Users that imported successfully stay in place, so fix the remaining rows and re-import them with Update Existing or Add and Update.

After the import, the component runs Joomla’s normal user-save event, so plugins that react to new users, such as newsletter list rules, run as if you’d saved each user by hand. Imported and updated users are also recorded in the User Actions Log when your site logs Users events.

How to Export Joomla Users to CSV or Excel

Step 1: Open Export and choose a format

Go to Components > User Import Export and click Export. Pick the format for the job:

• CSV for spreadsheets and other systems, with a comma, semicolon, tab or pipe delimiter.
• Excel (XLSX) for reports, with styled headers, auto-sized columns, a frozen header row and filters.
• JSON for APIs and applications.
• XML for systems that expect XML.
• SQL for database migration, as INSERT statements.

Step 2: Select the fields

Include only what you need: core fields (ID, username, name, email, registration date, last visit, block status), user groups, profile data, administrator user notes and any custom fields created for users.

Step 3: Filter the users

Narrow the export by name, username or email, user group, activation or blocked status, registration date range or last-visit date range. For example, export only the Registered group, or users who haven’t logged in this year.

Step 4: Set password handling

Choose to exclude passwords (best for reports), include the hash (only for moving users to another Joomla site), or use a placeholder. Plain-text passwords can never be exported, because Joomla only stores hashes.

Step 5: Preview, export and save as a template

Click Preview to see the first 10 matching records, then Export to download the file. If you’ll run the same export again, click Save as Template. Saved templates keep the format, fields, filters and options, and you can run them again from the Templates menu. Previous export files can also be downloaded again from the Logs until the retention period you set clears them.

Joomla User Import CSV Template

This example comes from the extension’s documentation. Copy it into a text editor, save it as a .csv file in UTF-8, and replace the sample rows with your own:

username,email,name,password,groups,block,profile_phone,profile_city
johndoe,john@example.com,John Doe,ChangeMe123!,Registered,0,+1234567890,New York
janedoe,jane@example.com,Jane Doe,SecurePass456!,"Registered, Author",0,+0987654321,Los Angeles
bobsmith,bob@example.com,Bob Smith,,Registered,0,,London

Column	What it holds	Required
username	Unique login name, 3 to 150 characters	Yes
email	Unique, valid email address	Yes
name	Full display name	Recommended
password	Plain text (hashed on import). Leave empty to auto-generate	Optional
groups	Group names, comma-separated inside quotes for more than one	Optional
block	0 = active, 1 = blocked	Optional
profile_*	Profile fields such as profile_phone or profile_city	Optional

JSON imports use an array of user objects, for example [{"username": "johndoe", "email": "john@example.com", "name": "John Doe", "groups": ["Registered"]}]. XML imports use a <users> root with one <user> element per account.

How to Migrate Users From One Joomla Site to Another

1. Back up both sites.
2. On the old site, export users with core fields, groups, profile data and custom fields, and choose include hashed passwords.
3. On the new site, create the same user groups and user custom fields, so the names match.
4. Import the file with Add and Update and Import from File for passwords. The bcrypt hashes are detected and kept, so users can log in with their existing passwords.
5. Validate first, fix any errors, then import and check the log.
6. Log in as a few test users and confirm their groups and access levels.

If you’re moving the whole site, not just users, follow our guide to transferring a Joomla site to a new server. If you’re coming from Joomla 3, read how to upgrade Joomla 3 to Joomla 6 first, because a full upgrade carries users over without any import.

Troubleshooting Joomla User Imports and Exports

The file upload fails

Check PHP’s upload_max_filesize setting, make sure the file type is CSV, XLSX, XLS, JSON or XML, and confirm the file isn’t corrupted.

Columns don’t auto-map

Headers must be in the first row. Remove special characters from header names and use standard names like username, email and name.

Validation errors on usernames or emails

Usernames must be unique and 3 to 150 characters long. Emails must be valid and unique, both inside the file and against existing users.

Excel export isn’t available

XLSX export needs the PhpSpreadsheet library (composer require phpoffice/phpspreadsheet). Use CSV in the meantime.

The export file is empty

Your filters are probably too narrow. Make sure at least one field is selected and that users exist in the chosen groups.

Large imports time out

Reduce the batch size in Options, raise PHP’s max_execution_time, or split the file into smaller batches.

Special characters look broken

Save the file as UTF-8. Excel’s default CSV encoding can mangle accented names.

Best Practices for Bulk User Imports

1. Back up first. See how to back up a Joomla website.
2. Test on staging with a small, representative batch before the full file.
3. Clean the source file: remove duplicates, fill required fields and fix invalid emails.
4. Create groups and custom fields first so mapped values have somewhere to go.
5. Choose the import mode on purpose. Add New Only is the safest default.
6. Treat exports as sensitive. Exclude passwords unless you’re migrating, store files securely and delete them when you’re done.
7. Read the log after every run instead of assuming every row went in.

FAQ

Can Joomla import users from CSV without an extension?

Not from the administrator. Joomla 4, 5 and 6 have no user import feature. Without an extension, you’d have to import into the database tables with phpMyAdmin, which skips validation and Joomla’s user plugins.

How do I export all users from Joomla to Excel?

Core Joomla can’t do it. Use an extension like JoomlaX User Import Export and choose Excel (XLSX) or CSV, or export the #__users table from phpMyAdmin as CSV and open it in Excel.

Can I import users with their existing passwords?

Yes, if the hashes come from a compatible source such as another Joomla site. JoomlaX User Import Export detects bcrypt hashes and keeps them, so users can log in with their current passwords. Hashes from incompatible systems won’t work, so use Require Reset instead.

How do I add imported users to specific user groups?

Add a groups column with group names, separated by commas for more than one, or set a Default User Group in the import options.

Can I update existing Joomla users in bulk?

Yes. Use the Update Existing Only or Add and Update import mode. Users are matched by email or username.

Are Joomla custom fields included?

Yes. User custom fields can be exported, and single-value custom fields can be imported and mapped to your file’s columns.

Will imported users get a welcome email?

Only if you enable Send email during the import. Each new user then gets one email with their username and a password or a link to set one.

Which Joomla versions does JoomlaX User Import Export support?

The documentation lists Joomla 5.x and 6.x, with PHP 8.1 or higher.

Need Help Moving Your Joomla Users?

For a simple list, the steps above are all you need. For migrations from other platforms, complex custom fields or sites with thousands of members, our Joomla development team can plan and run the move, or you can hire a Joomla developer for the project. If your site needs ongoing care afterwards, see our Joomla support and maintenance plans.

Ready to try it? See JoomlaX User Import Export and the documentation.

A Joomla module shows on the wrong pages when its Menu Assignment does not match the menu item Joomla used for that request (the Itemid). “On all pages except those selected,” a Home menu item that is not the URL you think, the Language Filter, and duplicate module copies are the usual causes. The module is published and the position works. The page map is wrong.

This is not an empty position. If the slot never renders on any page, read Joomla module position not showing first. Here you already see the module. You see it on Home when it should only be on Contact, or on every article when you ticked one menu item, or in two languages at once.

Joomla does not assign modules to URLs. It assigns them to menu items. Get the Itemid wrong and the module follows the wrong page.

What you will learn

• The four Menu Assignment values and what each actually does
• Why Home is a menu item, not “the slash URL”
• What happens on articles that have no menu item of their own
• How Language Filter hides or doubles modules
• How duplicate copies (Save as Copy) produce “it is everywhere”
• A click order that fixes the map without guessing

Official assignment help: How do you assign a module to specific pages? and the Joomla 4/5 user manual Module display by menu item.

How Joomla decides “this page”

Every frontend request Joomla can map has an Itemid: the id of a menu item. Modules in System → Site Modules look at that Itemid, plus Access and Language.

They do not look at the article id first. They do not look at the SEF path as a string. If you open an article from a blog, a tag list, a search result, or a module link, Joomla may reuse Home’s Itemid or another nearby item. The module then follows that Itemid, not the article you have in your head.

That is why “I assigned it only to News / Article / My Story” still shows the login module on that story: the request never used that article’s menu item.

Assignment	What Joomla does	Typical mistake
On all pages	Every Itemid	You meant “all except Home”
No pages	Never	Left over from a test. Looks like unpublished.
Only on the pages selected	Only ticked menu items	You ticked a hidden duplicate, not the item in the main menu
On all pages except those selected	Every Itemid except the ticks	You ticked nothing, so except-nothing means everywhere

Default for a new module is On all pages. Save as Copy keeps that unless you change the tab.

Step 1: Read the Menu Assignment tab on the live module

1. System → Site Modules.
2. Filter by Position so you are not editing a draft copy.
3. Open the module that actually appears on the wrong page (title in the frontend chrome if titles are on).
4. Open Menu Assignment.

Write down:

• The Module Assignment dropdown value.
• Which menus are expanded. A collapsed tree hides ticks.
• Whether Home is ticked. Home is often not the first row. It can sit in a second menu named “Hidden” or “System.”

If Assignment is On all pages, Joomla is doing what you asked. Change the dropdown before you blame Language or the template.

Use Expand: All so you see every item, including unpublished and hidden-menu items. Hidden menus still have Itemids. Pages that use them still count.

Step 2: Fix “On all pages except” the way the manual describes

The user manual’s breadcrumbs example is the pattern: On all pages except those selected, then tick only the pages that must not have the module.

For “everywhere except Home”:

1. Set Assignment to On all pages except those selected.
2. Click None on Assign to Menu Items so the tree is clear.
3. Tick Home (the default menu item, star in Menus).
4. Save. Check the site.

If you tick Home and leave other items ticked from an earlier “Only on selected” pass, “except” now excludes those too. Clear the tree first.

If you wanted “only Contact” and you used “except” by accident, the module appears on Home, blog, and everything else. Switch to Only on the pages selected and tick Contact only.

Official breadcrumbs walkthrough: Module display by menu item.

Step 3: Treat Home as a menu item, not as “the homepage URL”

Home is whichever menu item has Default (the star). It can be:

• Featured Articles
• a single article
• a blog category
• a component view (search, a directory, a shop front)

The public URL can be / and still be that Itemid. Assigning a module to a different item titled “Home” in another menu does nothing for /. Assigning to the article that is also the default Featured layout does nothing unless that article has its own menu item and the visitor used it.

Checks:

1. Menus → All Menu Items. Filter Default or look for the star. That row is Home.
2. Confirm you ticked that row, not a similarly named item in a second menu.
3. If you have two languages, you have one default per language. Tick the Home for the language you are testing, or both, depending on the goal.

A module set to “only Home” will also appear on many orphan pages (next step) because those requests keep Home’s Itemid. That looks like “wrong pages.” It is Itemid inheritance.

Step 4: Pages with no matching menu item inherit an Itemid

This is the bug operators hit after they “assigned it to the article menu item.”

You created Menus → Hidden → My Article (single article). You assigned the banner Only on the pages selected → My Article. It shows when you click that hidden item. It does not show when you click the same article from a category blog, from Featured, or from a related-articles module. Those requests never used My Article’s Itemid.

The reverse: a module assigned only to Home appears on that same blog article because the blog used Home’s Itemid (or the category blog item, if that is what you clicked).

Fix, pick one:

• Put a real menu item on every page that must have unique modules, including a hidden menu used only for Itemid. Assign modules to those items.
• Assign the module to the blog or category item visitors actually click, not to a hidden single-article item they never use.
• For “this article only,” a hidden single-article item works only if every link to that article includes that Itemid (menu, or a URL that still carries it). Do not expect /index.php/my-article without Itemid to stay unique.

Aliases: an Alias menu item is a pointer. Assignment to the alias and assignment to the target are different Itemids. Tick the item whose URL the visitor actually opens.

Step 5: Language Filter and the module Language field

On a multilingual site, System → Plugins → System – Language Filter is usually enabled. Each module has a Language field (right side of the Module tab): All, or one content language.

Rules that produce “wrong pages”:

• Module Language is English. You are viewing the French Home. The module is absent there (correct) and you think assignment is broken.
• Module Language is All. You duplicated the module for French but left the original on All. Both copies can show on French pages if assignment also matches.
• You assigned the English module to French menu items. Menu items are per language. Ticking a French item while the module is English still fails the language check.

Also check Menus for the same item in each language. “Only on Home” must tick English Home and French Home if the module is All and you want both homepages. If the module is English-only, tick English Home only.

Language strings in the module chrome (titles) are a different tool: Joomla language overrides. Overrides do not change which pages load the module.

Step 6: Find duplicate modules before you rewrite assignment

Save as Copy is how “I fixed assignment and it is still on every page” happens.

1. System → Site Modules.
2. Search the title. Sort by Position.
3. Look for the same module type in the same position: mod_custom twice in sidebar-right, or Login twice.

One copy is On all pages. One copy is Only on Contact. You edited the Contact copy. The All copy is what you still see on Home.

Unpublish or delete the extra copy after you confirm which id is in the URL of the module edit screen (id=).

Duplicates also come from:

• A template sample-data module you forgot (Cassiopeia “Site” custom modules).
• A language pack workflow that copied modules per language, then someone set Language back to All.
• Two login modules, one Guest and one Registered, both assigned to all pages. That is access, not assignment, but it looks like “the module is on the wrong page” after login.

Step 7: Do not confuse Access, Status, and cache with assignment

Quick exclusions so you stay on this job:

• Unpublished never appears. Wrong-pages means it does appear, just not where you wanted.
• Access (Public, Guest, Registered, Special) changes who sees it, not which Itemid. Guest modules vanish after login. That can look like “it disappeared on this page” when you actually changed user state.
• Cache: System – Page Cache or conservative cache can keep a Home HTML payload on another URL for a short time. Clear cache after assignment changes (System → Maintenance → Clear Cache). If a CDN sits in front, purge that too.
• Template style per menu item can change positions. The module still “shows on the wrong page” as in “the sidebar exists on Shop but not on Home” because Shop uses a different style. That is still a layout map. Confirm styles under the menu item, then read the position article if the slot is missing entirely.

Custom HTML in the module is not assignment. If you need different markup per section, use assignment plus two modules, or a child template override, not one module and a PHP hack in core.

A worked map (so the options stick)

Goal: promo banner on all pages except Home, and a different banner only on the Shop menu item.

Module	Position	Assignment	Ticks
Promo default	top-a	On all pages except those selected	Home only (the real default item)
Promo shop	top-a	Only on the pages selected	Shop (and Shop’s language twins if multilingual)

If Shop is a blog and products are opened without a Shop Itemid, the shop banner will not follow into the product. Add a hidden menu structure for product Itemids, or assign the shop banner to every item in the shop menu tree (Expand, then tick the parent and children).

Print, feeds, and “component only” pages

Some URLs are still Joomla menu items (or inherit Itemid) but you do not think of them as pages:

• Print and email article views often keep the article’s Itemid. A module assigned only to Home should stay off those views if the article has its own item. If print uses Home’s Itemid, the Home modules appear on print. That is the same inheritance as Step 4.
• Smart Search or search results may use the Search menu item. Assign modules to that item if the search layout should have them, or exclude it with On all pages except.
• A component with no site template modules in its own index is rare. More often the component uses the site template and still runs jdoc positions. If a shop checkout must be module-free, assign those modules with On all pages except and tick the checkout items.

Do not fight this with CSS display: none on every extra module. Assignment is the control. CSS hide still downloads the HTML and still runs the module PHP.

Read the dropdown first. Then Home. Then Language. Then search for a second module in the same position.

Key takeaways

1. Modules follow menu Itemid, not the article title in the browser tab.
2. New modules default to On all pages. Change Menu Assignment or they will be global.
3. On all pages except requires a clean tree, then ticks only on the pages to exclude. Empty ticks mean everywhere.
4. Home is the default menu item (star). Tick that row. A second item named Home does not control /.
5. Articles opened from blogs, tags, or modules often keep Home or blog Itemid. Hidden single-article items do not apply unless the visitor used them.
6. Language Filter plus module Language All plus a copied module is the usual double-display on multilingual sites.
7. Search Site Modules for duplicate titles and positions before you rebuild the assignment tree.
8. Clear cache after you save. Stale page cache looks like assignment did nothing.

If the layout is right on some menu items and the slot is empty on others because those items use another template, go to module position not showing. For ongoing assignment and multilingual cleanup on a production site, Joomla support and maintenance.

Related Joomla troubleshooting

• Joomla module not showing
• Module position not showing
• Customize without editing core

Frequently asked questions

Why is my Joomla module showing on the wrong pages?

Menu Assignment does not match the Itemid of the request. The dropdown is still On all pages, you ticked the wrong Home, Language Filter disagrees, or a duplicate module is still global.

How do I show a module on all pages except the home page?

Set Module Assignment to On all pages except those selected, clear the tree, tick only the default Home menu item, save, then clear cache. Confirm you ticked the starred Home, not a namesake.

Why does a module assigned to one article still show on other articles?

Those other URLs are not using that article’s menu Itemid. They are using Home or the category blog item. Create a menu item for each page that needs unique modules, or assign to the blog item visitors actually click.

Can Language Filter make a module appear in the wrong language?

Yes. A module set to All can show beside a language-specific copy. A module set to English will not show on French Itemids. Align Language on the module with the menu items you tick.

Does Access change which pages a module appears on?

No. Access changes which users see it on the pages where assignment already allows it. Guest vs Registered is not a substitute for Menu Assignment.

What does No pages do?

The module never displays, even if it is published. Use that only as a parking state. It is easy to confuse with unpublished.

Should I assign modules to alias menu items?

Assign to the item whose URL the visitor opens. An alias has its own Itemid. If people click the alias, tick the alias. If they click the target, tick the target.

A Joomla module position is not showing when the position name on the module does not match a real slot in the active template. Joomla only prints a module where index.php has a jdoc:include for that name, and where templateDetails.xml lists the same name. Chrome (the HTML wrapper) and CSS can also hide a slot that did render. This is a template wiring problem. It is not “the module is unpublished,” and it is not “it appears on the wrong pages.”

If the module is published, assigned to the page you are viewing, set to Public, and still missing from that layout region, stop toggling Status. Open the template files. The usual miss is a leftover Joomla 3 name (position-7, left) on a Cassiopeia or club template that never declared it.

Three places must use the same string: the module Position field, templateDetails.xml, and the jdoc name in index.php.

What you will learn

• How to tell a missing position from a module that is unpublished or assigned to other pages
• Where Cassiopeia and most Joomla 4, 5, and 6 templates declare positions
• How to preview positions with ?tp=1 without guessing
• Why a child template can list a position in XML and still not print it
• How module chrome and CSS make a rendered slot look empty
• What to change so the fix survives the next template update

This article does not walk unpublished modules, Access, Language, or Menu Assignment. Those belong to “module not showing” and to Joomla module showing on the wrong pages. Keep this page for chrome, index.php, and name mismatch.

What “position not showing” means

Joomla does not paint a magic box named “sidebar.” It does this:

1. The module row stores a position string (sidebar-left, bottom-a, debug).
2. The active site template (the style assigned to that menu item) reads templateDetails.xml so the Position dropdown has labels.
3. That template’s index.php (or a layout it includes) outputs <jdoc:include type="modules" name="sidebar-left" style="…" />.
4. Chrome wraps each module in that position. CSS then shows or hides the wrapper.

Break any of the first three and the slot is empty. Break the fourth and View Source still has the HTML, but you cannot see it.

Official references: Declaring module positions, jdoc statements, Module chrome, Cassiopeia templateDetails.xml.

What you see	Likely cause	Wrong rabbit hole
Empty region on every page that uses this template	Name mismatch or missing jdoc	Menu Assignment
Empty region only on some menu items	Those items use a different template style	“The module is unpublished”
Preview (?tp=1) shows the position, live page does not	Chrome or CSS, or you assigned a name preview invented	Cache only
Preview does not show the name you typed	XML and index.php never declared it	Access level
HTML in View Source, nothing on screen	Chrome class or user.css (display: none, zero height)	Reinstalling the module

Cassiopeia names vs leftover names

Cassiopeia (Joomla 4, 5, and 6) uses names like topbar, below-top, menu, search, banner, top-a, top-b, main-top, main-bottom, breadcrumbs, sidebar-left, sidebar-right, bottom-a, bottom-b, footer, debug.

Joomla 3 Protostar used position-0 through position-14, plus a few aliases. After a migration, Site Modules still holds those old strings. The dropdown may even let you type them. Cassiopeia will not print position-7. There is no jdoc for it.

Club templates (Helix, T4, Gantry, YOOtheme) have their own lists. Never assume left exists. Read that template’s XML.

Step 1: Prove it is a position problem

Open System → Site Modules. Open the module.

Confirm only this much, then leave:

• Status is Published.
• Access is a level the visitor has (Public for a guest test).
• Language is All, or the language of the page you are testing.
• Menu Assignment is On all pages, or includes the page you have open.

If any of those fail, this is not a position article. Fix Status or assignment first.

Then note the Position value exactly. Copy it. Spaces, underscores, and hyphens all count. sidebar-left is not sidebar_left. sidebar-left is not left.

Check Advanced → Module Style (chrome). If it is not “Inherited” or the template default, write that down. A missing custom chrome file can swallow output.

Step 2: See which template style is actually active

Positions live on a template, not on the site as a whole.

1. System → Site Template Styles.
2. Note which style is default (star).
3. Open the menu item for the page you are testing. Template Style may override the default.

If Home uses Cassiopeia and a landing page uses a club template, a module in sidebar-right can show on Home and vanish on the landing page because that club file never includes sidebar-right.

Child templates (Joomla 4.1+) add another layer. The public site must use the child style, not the parent, if you put jdoc lines only in the child. Setup: How to set up a Joomla child template. Safe file placement: Customize Joomla without editing core.

Do not edit Cassiopeia’s index.php in place. Put extra positions on a child, or they vanish on the next Joomla update.

Step 3: Preview the positions Joomla knows

Do not guess from a blog screenshot of Protostar.

1. System → Site Templates.
2. Toolbar Options.
3. Set Preview Module Positions to Enabled. Save.

On the frontend, append ?tp=1 to a URL with no query string, or &tp=1 if the URL already has ?.

You should see outlined boxes with names. Official walkthrough: Module positions (Joomla User Manual).

Compare:

• If your module’s position appears in the outline, the template declared it. The problem is assignment to a different name, chrome, CSS, or a different style on that menu item.
• If your module’s position does not appear, XML or index.php (or both) never defined it for this template.

Turn Preview back to Disabled on production when you finish. The outlines are a diagnostic, not a feature for visitors.

Step 4: Match the name in templateDetails.xml

On the active template (child if you use one), open templateDetails.xml. Find the <positions> block.

Every <position>sidebar-left</position> is only a label for the Module Manager dropdown. It does not print HTML by itself. The docs are explicit: adding a tag in XML is not enough. You still need a jdoc in the layout. See the Cassiopeia XML notes on docs.joomla.org.

Typical failures:

• You typed Sidebar-Left in the module. XML has sidebar-left. Use lowercase, no spaces.
• You added <position>promo</position> to the child XML so it appears in the dropdown, then assigned the module to promo, but never added a jdoc (next step).
• You are reading the parent XML while the site runs the child, or the reverse.

If the name is missing from XML, the Position list will not offer it unless you type a custom value. Custom values still need a matching jdoc.

Step 5: Match the jdoc in index.php

Open index.php for the same template that is assigned to the page. Search for jdoc:include and type="modules".

You need a line equivalent to:

<jdoc:include type="modules" name="sidebar-left" style="card" />

The name attribute must equal the module Position field. The style attribute is chrome (none, html5, card, noCard, or a custom chrome name). If style is omitted, Joomla uses none.

Cassiopeia often wraps positions in countModules() so empty columns collapse:

<?php if ($this->countModules('sidebar-left', true)) : ?>

That is correct. If no module uses that exact name, the column does not render. It looks like “the sidebar never existed,” which is the template working as designed.

Failures at this step:

• XML lists promo. index.php still has only bottom-a. The dropdown lied. The page never included promo.
• index.php includes sidebar-left. The module is on left.
• You copied a Joomla 3 index.php fragment into a Joomla 5 child. The old jdoc names do not match Cassiopeia CSS or grid.
• The jdoc sits inside a condition that is false (for example a width check, an error-page only branch, or a homepage-only if).

Add missing positions in a child index.php if you must fork the layout. Prefer using an existing Cassiopeia slot when one already sits where you need the module.

Step 6: Check chrome before you rewrite CSS

Chrome is the wrapper around the module, not the module’s own tmpl. Core names include none, html5, outline, and table. Cassiopeia adds card and noCard. Custom chrome lives in html/layouts/chromes/{name}.php. Docs: Module chrome and Applying custom module chrome.

A position can “not show” when:

• Module Style on the module is set to a chrome file that does not exist on this template. PHP can fail inside the chrome include. On a staging copy, set Error Reporting to Maximum once and reload.
• Chrome is none and your CSS only targets .card. The content is in the HTML. It has no box, no title, no padding. You thought the position was empty.
• A custom chrome prints nothing when the title is hidden, or it wraps output in a class your CSS sets to display: none.
• You overrode chrome in the parent and the child does not inherit that file until you copy it. Child templates do not magically copy every parent html/ file.

If you need different markup around a module, add a chrome file in the child. Do not edit modules/mod_*/tmpl in core. Same rule as other overrides: Joomla plugin override for plugin tmpl, child html/ for module chrome.

Step 7: Confirm the HTML, then the CSS

View Source or Inspector on the published page.

• No module HTML at all: name mismatch, missing jdoc, wrong template style, or (if you skipped Step 1) the module never loaded for that request.
• Module HTML present: the position works. Chrome or CSS is hiding it. Check user.css, template CSS, and browser width (some templates drop sidebar-right under a breakpoint by using d-none / Bootstrap utilities).

Cassiopeia custom CSS belongs in media/templates/site/{template}/css/user.css on the active template. A child does not load the parent’s user.css. If you hid .sidebar-right while testing and then created a child, the hide may still live on the parent, or the reverse.

If a script is emptying the node after paint, that is a JavaScript issue, not a missing position. Separate guide: Add custom JavaScript to Joomla.

Clear Joomla cache (System → Maintenance → Clear Cache) and the browser cache after CSS or chrome changes. Conservative caching can keep an old layout where the column was empty.

Step 8: Fix the mismatch (order that survives updates)

1. Pick a position that already exists in both XML and index.php on the active template. Reassign the module to that name. This is the usual migration fix (position-7 → sidebar-right).
2. If you truly need a new slot, add the <position> in the child templateDetails.xml, add the matching jdoc in the child index.php, assign the child style, then set the module Position to that name.
3. Set Module Style to Inherited or to a chrome that exists (card / noCard on Cassiopeia).
4. Remove any display: none on that region in user.css.
5. Preview with ?tp=1, then disable preview.

Do not “create” a position by only typing a new string in the module. Joomla will store it. Nothing will print it.

Work top to bottom. Reassigning to an existing Cassiopeia slot is faster than inventing promo.

Child templates and extra positions

On Joomla 4.1+, 5, and 6, extra positions belong on a child:

• The child can inherit the parent index.php until you copy one. Inherited index.php will not contain your new jdoc. XML-only positions still will not show.
• After you copy index.php into the child, you own that file. Diff it after Cassiopeia updates. Markup in core index.php can change.
• Positions you add must stay lowercase and unique.

Joomla 6 ships Cassiopeia Extended as a child of Cassiopeia. Treat Extended as a child: do not hack the parent, and do not assume Extended’s XML matches a custom child you made last year.

When the position shows in preview only

?tp=1 injects outline chrome so empty slots are visible. A live page without tp=1 will not show a box if countModules() is zero. If preview shows promo because you added XML, but live still has no module HTML, you still lack a jdoc or the module is not using that name.

If preview and live both lack the name, you are on the wrong template style.

Key takeaways

1. A missing module position is a name mismatch between the module, templateDetails.xml, and index.php, or it is chrome and CSS hiding a slot that did render.
2. Cassiopeia does not print Joomla 3 names such as position-7 or left. Reassign to sidebar-left, sidebar-right, bottom-a, and the rest of the Cassiopeia list.
3. XML only feeds the Position dropdown. A jdoc:include type="modules" name="…" is what prints the slot.
4. Preview Module Positions (?tp=1) after enabling it under Site Templates → Options. Disable it again on production.
5. Menu-item Template Style can switch layouts. The same module position can exist on Cassiopeia and not on the landing template.
6. Put new positions and chrome on a child template. Do not edit the parent index.php.
7. If View Source has the module, fix chrome or CSS. If it does not, fix the name or the jdoc.
8. Unpublished, Access, Language, and Menu Assignment are a different diagnosis. Do not debug those here.

Need this traced on a live site after a template swap? Joomla support and maintenance.

Related Joomla troubleshooting

• Joomla module not showing
• Module showing on the wrong pages
• Customize without editing core

Frequently asked questions

Why is my Joomla module position not showing?

The position string on the module does not match a jdoc in the active template’s index.php, or it is not listed in templateDetails.xml. Reassign to a name the template already prints, or add both the XML tag and the jdoc on a child template.

Does declaring a position in templateDetails.xml make it appear?

No. That file only lists names for the Module Manager. The layout file must include <jdoc:include type="modules" name="the-same-name" />.

Where did position-7 go in Joomla 5?

Cassiopeia never used position-7. After a Joomla 3 migration, reassign those modules to sidebar-right or another Cassiopeia position you confirm with ?tp=1.

Can a child template hide parent positions?

The child uses the parent layout until you copy index.php. Parent positions still show in that case. If you copy index.php and drop a jdoc, that slot disappears. XML on the child cannot restore it without the include.

Why do I see the module in View Source but not on the page?

The position rendered. Chrome or CSS is hiding it. Check Module Style, custom chrome files, Bootstrap d-none classes, and user.css.

Is this the same as the module showing on the wrong pages?

No. Wrong pages is Menu Assignment, Home, language filter, and duplicate modules. Empty slot on the pages where it should already load is this article.

Should I edit Cassiopeia index.php to add a position?

No. Create a child, copy index.php into the child if you must change the layout, and add the position there. Core updates replace the parent.

Short answer: You can’t jump straight from Joomla 3 to Joomla 6. The supported path is 3.10 → 4.4 → 5.4 → 6.x, with a backup, a Pre-Update Check, and an extension review at every step. Only need Joomla 5? Follow the same steps and stop at 5.4; the Joomla 3 to 5 migration is the first three hops. Joomla 3 and Joomla 4 no longer get security fixes. Joomla 5 bug fixes end on October 13, 2026, and Joomla 6 is supported until October 2029. The core update is usually the easy part. Most of the work goes into extensions, templates, and hosting.

Current versions (as of September 30, 2026)

• Joomla 6.1.4 and Joomla 5.4.9: security and bugfix releases, published September 29, 2026 (release announcement).
• Joomla 6.2: Release Candidate 1 is out for testing only. General availability is planned for about October 13, 2026 (RC announcement).
• The last releases for the older lines are 3.10.12 and 4.4.14 (from Joomla’s official update feed).

This guide brings together what we’ve learned from running this upgrade path on client sites. It points you to the official Joomla documentation for exact, button-by-button steps, and focuses on the decisions and problems those docs assume you’ve already worked out.

---

1. Which Joomla version are you on, and why upgrade now?

In the administrator, open System → System Information and write down three things: your Joomla version, your PHP version, and your database type and version. Everything else in this guide depends on those three numbers.

Version line	Status	Key dates (official)
Joomla 3.x	End of life	Support ended in August 2023
Joomla 4.x	End of life	Security support ended in October 2025 (Joomla version support table)
Joomla 5.x	Security fixes only, soon	Bugfix support ends October 13, 2026; security-only support ends October 12, 2027 (Joomla roadmap)
Joomla 6.x	Current major	Released October 14, 2025; bugfixes until October 17, 2028; security until October 16, 2029 (Joomla roadmap)

What this means in practice:

• On Joomla 3 or 4? You’re running a CMS that no longer gets security patches. The September 29, 2026 release alone fixed 16 core security issues in 5.4 and 6.1 (release notes). Joomla 3 and 4 sites don’t get fixes like these.
• On Joomla 5.4? You’re fine for now, but bug fixes stop in October 2026. Plan the move to 6.x on staging while you still have time.
• Hosting pressure: Joomla 6 requires PHP 8.3. Hosts are phasing out old PHP versions, so a Joomla 3 site on PHP 7.x can break when your host upgrades PHP, whether or not you’re ready.

2. Know the path before you start

Stage	You must be on	You move to	Official guide
1	Latest Joomla 3.10.x	Joomla 4.4.x	Joomla 3.x to 4.x Step by Step Migration
2	Joomla 4.4.x	Joomla 5.4.x	Joomla 4.4.x to 5.x Planning and Upgrade
3	Joomla 5.4.x	Joomla 6.x	Joomla 5 to 6 Planning and Upgrade

Joomla calls 3.10 → 4 a “mini-migration” because the core upgrades with one click, while third-party extensions may not. It calls 4.4 → 5 and 5.4 → 6 upgrades. If you’re on 3.9 or older, update to 3.10.12 first. On Joomla 1.5 or 2.5, you’re doing a rebuild or data migration, not an in-place upgrade.

A note on jUpgrade: Some older videos still recommend jUpgrade. It was built for Joomla 1.5-era migrations and plays no part in the 3 → 4 → 5 → 6 path, which runs through the core Joomla Update component.

Server requirements for each hop

Target	PHP (minimum)	Database (minimum supported)	Source
Joomla 4.x	7.2.5	MySQL 5.6 / PostgreSQL 11	3.10 → 4.0 notes
Joomla 5.x	8.1.0 (8.3 recommended)	MySQL 8.0.13 / MariaDB 10.4 / PostgreSQL 12	Joomla 5 requirements
Joomla 6.x	8.3.0 (8.4 recommended)	MySQL 8.0.13 / MariaDB 10.6 / PostgreSQL 14	Joomla 6 requirements

Joomla 6 also needs the PHP modules json, simplexml, dom, zlib, gd, and a database driver (mysqlnd, pdo_mysql, or pdo_pgsql), plus a memory limit of at least 256 MB. If your host can’t run PHP 8.3, you’ll stop at 5.4 until you change hosts, so sort out hosting before you spend a weekend on 3 → 4. Our Joomla PHP.ini settings guide covers memory and execution limits.

3. Pre-upgrade audit: extensions, templates, and custom code

Most upgrade failures come from third-party code, not the Joomla core. To see which installed extensions will break, run a Joomla 6 compatibility check first. Before you touch anything:

1. Export an inventory. Go to Extensions → Manage and filter by type: Package, Component, Module, Plugin, Template, Library. For each item, record the name, version, developer, and whether it’s in use.
2. Label every extension with one of these:
   • Keep: the developer offers Joomla 5.4 and Joomla 6 builds.
   • Replace: abandoned, or Joomla 3-only. If it’s dead on Joomla 4, it’s dead on Joomla 6.
   • Remove: installed but not used. Uninstall packages first, so their modules and plugins go with them.
3. Check against Joomla 6, not just Joomla 4. An extension that only supports Joomla 4 means paying for the same migration twice.
4. Find custom code. Look for custom components, templates/YOUR_TEMPLATE/html/ overrides, and CLI or cron scripts. You can test extension and template ZIPs for Joomla 6 problems with our free Joomla Migration Scanner, which runs in your browser, and look up replacements for each finding in the Joomla Migration Reference.
5. Clean up the content. The official 3.10 guide recommends emptying the trash (articles, categories, menu items) and fixing the database schema before you migrate.

If the audit turns up more rewrites than you have time for, that’s the part of the job a Joomla upgrade team usually takes on. Everything else in this guide you can still do yourself.

Extension	Type	Version	Developer	In use?	Decision (Keep/Replace/Remove)	Notes
Akeeba Backup	Component	Joomla 3 build	Akeeba Ltd	Yes	Keep	Update to the Joomla 4, 5 and 6 builds at each hop. Take a backup before every hop.
K2	Component	2.x	JoomlaWorks	Yes	Replace	Move items to core articles while still on Joomla 3. Map extra fields to custom fields and 301-redirect changed URLs.
sh404SEF	Component	Joomla 3 build	Weeblr	Yes	Replace	Install 4SEF + 4SEO on Joomla 3 and run their sh404SEF import before the 3 → 4 migration.
Site template (Helix3)	Template	Joomla 3 build	JoomShaper	Yes	Replace	Rebuild the layout in Helix Ultimate on staging, then remove Helix3 and its plugins.
ChronoForms	Component	v6	ChronoEngine	Yes	Replace	Install ChronoForms v8 alongside v6, rebuild the forms, and test email and custom PHP actions.
JComments	Component	3.x	Original project (no longer developed)	Yes	Replace	Back up the _jcomments tables, then move to the JComments 4 community fork.
Old slideshow module	Module	1.x	Third-party	No	Remove	Not published on any page. Uninstall it before the upgrade.

4. Backups and staging: never upgrade the live site first

• Take a full backup (files and database) before every hop, not just once at the start. Akeeba Backup is the tool most Joomla professionals use. See how to back up a Joomla website.
• Test the restore. Restore the backup to a staging location at least once. An untested backup isn’t a rollback plan.
• Build staging on a subdomain, a subfolder, a local stack, or a temporary hosting account, as the official guide suggests. Match the PHP and database versions you’ll run in production.
• Keep your Joomla 3 backup until the site has been stable on Joomla 6 for a while. You’ll want the original data if an extension vendor turns out to have no Joomla 6 build.
• Go live last. Do every hop on staging, test it, and then promote the finished site.

5. Step by step: 3.10 → 4.4 → 5.4 → 6

Step 1: Joomla 3.10 → 4.4 (the Joomla migration step)

1. On staging, update to the latest 3.10.x and fix the database schema (Extensions → Manage → Database → Fix).
2. Go to Components → Joomla Update → Options and set Update Channel to Joomla Next. This shows the Pre-Update Check. Don’t click update yet.
3. Read both parts of the check: Required/Recommended Settings and Extensions. Update what you’re keeping and uninstall what won’t survive. The official guide also lists old core leftovers to remove: plg_content_geshi, and the templates Beez_20, Beez5, Atomic, and Bluestork. Protostar disappears in Joomla 4.
4. Switch to a core template (Protostar or Beez3) so Joomla 4 has a working default. You’ll replace it after the upgrade.
5. Run the update. Then go to System → Maintenance → Database, check the schema, clear the cache, and test.
6. Move to the latest 4.4.x before going further.

What the Pre-Update Check really tells you: it reads each developer’s compatibility tag. It doesn’t run the code. “Missing Compatibility Tag” means the developer never told Joomla anything, so ask the developer. An extension can show as compatible and still crash with your overrides.

Step 2: Joomla 4.4 → 5.4

1. Once 4.4 is stable, switch PHP to 8.1 or newer (8.3 is recommended). Joomla 4.4 runs on PHP 8.1, so change PHP while you’re still on 4.4 and retest.
2. Update your extensions to their Joomla 5 builds.
3. Set the channel to Joomla Next, run the Pre-Update Check, and upgrade to 5.x. The Behaviour – Backward Compatibility plugin is enabled during this upgrade, which lets older extension code keep working for now.
4. Work through the official 4.4 → 5 guide’s notes on removed or changed core pieces. For example, the old Search component should give way to Smart Search.
5. Update to the latest 5.4.x. Joomla 6 will only install from 5.4.

Step 3: Joomla 5.4 → 6.x (the plugin step most guides skip)

Joomla 5.4 ships with two plugins with almost identical names (official compatibility plugin notes):

Plugin	Required state before upgrading to 6
Behaviour – Backward Compatibility (no number)	Disabled, and your site must still work with it off
Behaviour – Backward Compatibility 6	Enabled (Joomla 5.4 installs it enabled by default)

The official procedure:

1. On staging, disable Behaviour – Backward Compatibility. Click through the whole site and the administrator.
2. If something breaks, turn the plugin back on, find the extension that depends on it, and update, replace, or remove that extension, all while you’re still on 5.4. Joomla’s reasoning: it’s much safer for an incompatible extension to fail on 5.4, where you can re-enable the plugin, than halfway through the 6 upgrade.
3. Once the site works with that plugin off, confirm PHP 8.3+ and a supported database, then take a fresh backup.
4. Set the channel to Joomla Next, run the Pre-Update Check, and upgrade to the current 6.1.x. Once 6.2.0 is out, you can move to it.

If the administrator won’t load after you disable the plugin, re-enable it directly in the database (use your own table prefix):

UPDATE jos_extensions SET enabled = 1
WHERE type = 'plugin' AND folder = 'behaviour' AND element = 'compat';

Behaviour – Backward Compatibility 6 is a bridge, not a permanent fix. Joomla says Joomla 7 won’t provide the same compatibility layer for Joomla 5-era extensions, so treat any extension that still needs it as technical debt.

If a hop fails part-way (white screen, missing classes, database errors), stop and use the Joomla upgrade issues troubleshooting guide before retrying.

6. Common blockers and their replacements

Extension	Status	What to do
K2	JoomlaWorks announced K2 won’t be released for Joomla 4/5 (May 2024). There’s an unofficial community fork (K2ForJ4).	Move K2 content to core articles while you’re still on Joomla 3 (see K2 to Joomla articles). Map extra fields to custom fields and add 301 redirects for changed URLs. For large sites, see our K2 migration service.
sh404SEF	Joomla 3-only; discontinued August 17, 2023.	While you’re still on Joomla 3, install 4SEF (SEF URLs) and 4SEO (metadata, redirects) and use their sh404SEF import wizards. The imports need sh404SEF data on the site, so they must happen before the 3 → 4 migration.
T3 Framework templates	Built for Joomla 3. JoomlArt’s current framework is T4, and there’s no direct conversion.	Rebuild on a Joomla 5/6 template: T4, another maintained framework, or Cassiopeia with a child template. Budget it as a redesign, not a setting change.
Helix3 templates	JoomShaper’s current framework is Helix Ultimate. It’s a separate framework, with no one-click upgrade from Helix3 (JoomShaper forum).	Recreate the layout in Helix Ultimate on staging, then remove the Helix3 template and its plugins.
ChronoForms v5/v6	ChronoForms v8 supports Joomla 3 to 6 and requires PHP 8+.	Install v8 alongside the old version on Joomla 3, rebuild or import forms, and test email and custom PHP actions before upgrading the core.
JComments	The original is no longer developed. The community fork JComments 4 supports Joomla 4.2+ and 5, and a Joomla 6/PHP 8.3 beta has been released.	Back up the _jcomments tables, uninstall v3 (your comments stay in the database), install the fork, then repair the database and reset permissions (steps in the fork’s README).
VirtueMart	VirtueMart 4.6.x supports Joomla 3.10, 4, and 5. VirtueMart’s developer says the unnamespaced 4.x line will never run on Joomla 6, and a namespaced VirtueMart 5 is in development/beta.	Upgrade VirtueMart to the build for each target Joomla version before each core hop. For stores, 5.4 may be the sensible stopping point until a stable Joomla 6 VirtueMart release exists. Test checkout, payment, and shipping plugins every time. See VirtueMart upgrades.

Verify each vendor’s status yourself on the day you start. This list reflects what we could confirm on September 30, 2026. When a site has two or more of these blockers, the extension work usually takes longer than the core upgrade. Plan for that, whether you handle it in-house or through a Joomla upgrade service.

7. Fixing templates and layout overrides

Joomla 4 replaced Bootstrap 2 and MooTools with Bootstrap 5 and the Web Asset Manager, so a Joomla 3 template, or an override copied across from one, will break layouts, module chrome, or the whole page.

1. Isolate the template first. Set the site template to Cassiopeia. If the site renders correctly, the CMS is fine and the problem is your old template.
2. Update commercial templates to the vendor’s release for your Joomla version (Helix Ultimate, T4, Gantry, and so on).
3. Compare each override in templates/YOUR_TEMPLATE/html/ with the new core layout it replaces. Treat old overrides as rewrites, not file copies.
4. For the 6.x hop, search overrides for patterns Joomla 6 removed. Items returned as stdClass break $item->get('title') (use $item->title), and $app is no longer available in plugin layouts (use $this->getApplication()). See the official removed and backward-incompatible list.
5. Put your real template back only after you’ve clicked through the whole site.

If an override stops applying after the upgrade, work through why Joomla template overrides stop working.

8. Common errors and how to fix them

• White screen or 500: an extension, template or .htaccess fatal; read administrator/logs/joomla_update.php and disable it.
• Class “JTable”/”JFactory” not found: enable the Backward Compatibility (6) plugin, then update the old extension.
• “Unknown column” or missing table: System → Maintenance → Database → Update Structure.
• Next version never offered: switch the update channel to Joomla Next and meet the PHP minimum.
• Download fails or stalls: raise PHP limits or use Upload & Update (update error fixes).

Full symptom-by-symptom fixes, recovery SQL and schema repair: How to fix Joomla upgrade issues.

9. Post-upgrade checks: SEO, redirects, and speed

Once the final hop is on staging and working, check these before and just after go-live:

• Functionality: homepage, login, registration, contact and other forms, search, checkout and payments, multilingual switching, ACL-restricted pages, and scheduled tasks (old cli/ scripts need rewriting as console commands on Joomla 6).
• URLs: crawl the old site and the staging site with any SEO crawler, then compare. Every old URL should return 200 or a single 301 to its new equivalent. Pay special attention to K2 and sh404SEF URLs.
• Redirects: a fresh .htaccess drops hand-written rules (www, HTTPS, legacy aliases). Use the core Redirect component or your server config for 301s. Our Joomla .htaccess guide covers the common rules.
• Indexing signals: check the robots meta tags (staging is often set to noindex, and that setting sometimes goes live with the site), canonical tags, your XML sitemap, and structured data. Joomla 5 and 6 include a core Schema.org system plugin, so check it doesn’t duplicate markup from an SEO extension.
• Search Console: submit the sitemap and watch Coverage and 404 reports for the first few weeks.
• Speed: test key templates with PageSpeed Insights before and after, enable caching, and remove leftover jQuery or legacy assets you no longer need.
• Security: remove unused extensions and old admin accounts, and make sure you’re on the latest 6.1.x or 5.4.x security release.

10. Managing upgrades across many Joomla sites

Agencies and IT teams with dozens of sites run into the same problem as the Stack Exchange question on managing updates for multiple sites: doing every site by hand doesn’t scale.

• Standardize first. Group sites by Joomla version, template framework, and key extensions. Sites with the same stack can share one tested runbook.
• Use a central dashboard for version and extension status and routine updates. Options include self-hosted Akeeba Panopticon and hosted services like Watchful or mySites.guru. Compare their current features, since this guide doesn’t endorse any of them.
• Use the CLI where you can. Joomla 4 and later include a command-line tool (php cli/joomla.php) for checking and applying core updates, which fits scheduled or scripted maintenance. Keep major-version upgrades as a staging-first process per site.
• Pilot, then batch. Upgrade the simplest site in each group first, record every fix, then roll out to the rest.
• Track support dates. Put October 13, 2026 (end of Joomla 5 bug fixes) and October 12, 2027 (end of Joomla 5 security fixes) on the calendar for every Joomla 5 site you manage.

For ongoing patching after the upgrade, see Joomla support and maintenance.

11. DIY or hire help?

You can reasonably do this yourself if:

• The site runs mostly core Joomla and a few well-maintained extensions
• Your host already supports PHP 8.3 and MySQL 8.0.13+ or MariaDB 10.6+
• You’re comfortable restoring a backup and editing a database row

Consider a professional Joomla upgrade if:

• You’re still on Joomla 3 with K2, sh404SEF, a T3/Helix3 template, or custom components
• The Pre-Update Check lists extensions you can’t replace
• Disabling the Joomla 5 Backward Compatibility plugin breaks the site and you can’t find the cause
• Two attempts have already left the database or the administrator broken
• Checkout, memberships, or bookings bring in revenue and downtime costs money

Whoever does the work, insist on the same things: a written extension plan, a tested backup, a staging site you can review, a redirect map, and a rollback plan.

FAQ

Can I upgrade Joomla 3 directly to Joomla 6?

No. The supported path is 3.10 → 4.4 → 5.4 → 6.x. Joomla 6 only installs from 5.4, and each hop needs its own backup and Pre-Update Check.

Should I stop at Joomla 5 or go all the way to Joomla 6?

Go to Joomla 6 when your hosting runs PHP 8.3 and your key extensions have Joomla 6 builds. Stopping at 5.4 makes sense only as a temporary step (for example, while waiting for a stable Joomla 6 VirtueMart). Joomla 5 bug fixes end on October 13, 2026, and security fixes end on October 12, 2027.

Is Joomla 4 still supported?

No. Joomla 4’s security support ended in October 2025. The last release was 4.4.14.

How long does a Joomla 3 to 6 upgrade take?

It depends almost entirely on your extensions, templates, and custom code. A mostly core site can be done fairly quickly, while sites with K2, e-commerce, or custom components take much longer. Do an inventory before you commit to a timeline.

Will upgrading Joomla hurt my SEO?

Not if URLs are preserved or 301-redirected, robots and canonical settings are checked, and the sitemap is resubmitted. Most SEO losses come from changed K2 or sh404SEF URLs, or from a noindex setting carried over from staging.

Is Joomla 3 to 6 a Joomla migration or an upgrade?

Both. The 3.10 → 4.4 step is a Joomla migration: Joomla’s own documentation calls it a “mini-migration” because the core moves with one click but extensions and templates built for Joomla 3 often need replacing or rewriting. The 4.4 → 5.4 and 5.4 → 6 steps are upgrades within the same codebase. Most of the work in a Joomla migration is the extension and template audit, so start there.

What’s the difference between a Joomla update and an upgrade?

An update stays within one major version (for example, 6.1.3 → 6.1.4) and uses the Default update channel. An upgrade changes the major version (for example, 5.4 → 6) and needs the Joomla Next channel, a Pre-Update Check, and an extension review.

Do I need the Backward Compatibility plugin?

When going from 4.4 to 5, the Behaviour – Backward Compatibility plugin helps older extensions keep working. Before upgrading from 5.4 to 6, it must be disabled, and Behaviour – Backward Compatibility 6 must be enabled.

Can I still use jUpgrade?

No. It was built for Joomla 1.5-era migrations. The 3 → 4 → 5 → 6 path runs through the core Joomla Update component.

---

Need a hand? If your site has blockers you’d rather not untangle yourself, our Joomla upgrade service handles the audit, staging, and each hop, with you signing off before anything goes live.

Disabling right click in Joomla means stopping the browser context menu on the public site so casual visitors cannot open “Save image as” or similar shortcuts in one click. On Joomla 3, 4, 5, and 6 the reliable way is a system plugin that injects the behaviour sitewide (or for images only) without editing the template. It is a soft deterrent, not real copy protection.

This guide explains what the feature does, when it helps, how to turn it on with Right Click Disable from Infyways, and what still fails if you expect it to stop theft.

What you will learn

• What right-click disable blocks, and what it never blocks
• How to disable right click in Joomla with the Right Click Disable plugin
• Why a plugin beats pasting scripts into a commercial template
• Images-only versus sitewide scope
• UX, accessibility, and SEO trade-offs before you enable it

What disabling right click does

Browsers open a context menu on right click (and on some long-press gestures). A Joomla right-click plugin cancels that default menu on the front end. Official event behaviour is documented on MDN’s contextmenu page.

Goal	Plugin helps?	Better approach
Stop casual “Save image as”	Partially	Watermarks, low-res previews, licensed galleries
Stop View Source / Inspect	No	Source is always available in the browser
Stop scrapers and bots	No	Rate limits, firewall rules, non-public assets
Reduce casual image grabs on a portfolio	Often yes	Combine with watermarking
Protect paid downloads	No	Login walls and expiring file links

Some browsers still offer ways around a cancelled menu (for example Firefox with Shift held while right-clicking). Mobile long-press menus vary. Treat the feature as a UX preference for galleries and content sites, not as security.

Plugin versus custom code

Approach	Who it fits	Risk
Right Click Disable plugin	Most site owners and agencies	Low. Toggle in the administrator. Survives template updates
Hand-edited template JavaScript	Developers who own the whole template	High. Commercial template updates wipe custom files. Easy to break the admin or forms
Random “paste this in index.php” snippets	Nobody long term	Breaks on Joomla 4+ asset changes and child-template setups

If you only need the outcome, use the plugin. Custom scripts belong in a maintained child template when you already have a developer on retainer, not as a substitute for an extension that is built, tested, and update-safe.

Step 1: Decide the scope

1. Whole site: every public page loses the context menu. Avoid this on heavy form or SaaS-style sites.
2. Images and media: visitors keep normal menus on text and links. Best default for portfolios and magazines.
3. Selected sections: only a gallery or a protected category. Use when the rest of the site should stay normal.

Pick the narrowest scope that solves the complaint you actually get (usually image saving).

Step 2: Install Right Click Disable

1. Get the package from the Joomla Extensions Directory listing or your JoomlaX download area. Live behaviour: Right Click Disable demo.
2. In the administrator open System → Install → Extensions (Joomla 4, 5, 6) or Extensions → Manage → Install (Joomla 3).
3. Upload and install the ZIP.
4. Open System → Plugins (or Extensions → Plugins on Joomla 3).
5. Search for Right Click Disable and open it.
6. Set Status to Enabled.
7. Enable Disable Right Click. Choose images-only or related options if your build offers them.
8. Save & Close.
9. Clear Joomla cache, then test the public site in a private window.

Confirm /administrator/ still has a normal context menu. The plugin is meant for the site front end. If the admin UI is affected, disable the plugin and contact support with your Joomla version.

Step 3: Configure for your content type

• Portfolio / photography: prefer image-focused protection so writers and clients can still use browser menus on text.
• Brochure marketing site: sitewide can be acceptable if you have few forms.
• Membership or course site: do not use right-click disable as the paywall. Protect files on the server.
• Multilingual: enable once. The front-end script applies per page load, not per language pack.

Step 4: Test before you call it done

1. Right-click a paragraph and an image. Confirm the scope you chose.
2. Open a contact or login form. Confirm paste and browser tools still feel usable.
3. Check Chrome, Firefox, Edge, and Safari, plus one phone long-press.
4. Clear CDN cache if the old page without the script is still served.

Why template hacks fall apart

Forum snippets that dump JavaScript into index.php or a random module chron look easy. They fail when:

• You update Helix, T4, Gantry, or another commercial template and lose the edit
• Joomla 4+ expects assets through the Web Asset Manager, not ad-hoc script tags
• The script also runs in the administrator and blocks your own workflow
• A cache or optimisation extension reorders scripts and the listener never binds

A dedicated system plugin is built for those edges. That is the product Infyways maintains on JED so agencies do not babysit template forks for a five-line behaviour.

Accessibility, UX, and SEO

• Accessibility: some people use the context menu for browser features. Prefer images-only when you can.
• UX: silent blocking beats an alert on every click.
• SEO: crawlers do not need the context menu. Enabling or disabling right click does not move rankings by itself. Content quality still does.
• Legal: watermarks and copyright notices matter more than this feature.

When to skip right-click disable

• Documentation hubs and apps full of forms
• Products that teach “right-click to download”
• Any pitch that this “secures” paid media. Use authentication instead

Need the plugin installed on a client site, wired to a gallery, or bundled in a white-label stack? Infyways can handle that under Joomla plugin development or contact us.

Key takeaways

1. Right-click disable is a soft deterrent for casual copying, not security.
2. Use Right Click Disable for a maintained, toggleable solution on Joomla 3 through 6.
3. Prefer images-only when the complaint is photo theft.
4. Avoid pasting one-off scripts into commercial templates.
5. Test the administrator and forms after enabling.
6. SEO neither rewards nor punishes this feature on its own.

Frequently asked questions

How do I disable right click in Joomla?

Install and enable the Right Click Disable system plugin, set Disable Right Click to Yes, clear cache, and test the front end.

Does disabling right click protect my images?

Only against casual use. Anyone can still download images from the page source, a screenshot, or the image URL.

Does Right Click Disable work on Joomla 5 and Joomla 6?

Yes. Use a current package from JED or JoomlaX that lists your Joomla major.

Can I disable right click on images only?

Yes, when the plugin options (or your project brief) include image-focused mode. That is usually better than a sitewide block.

Will this hurt SEO?

No. Search engines do not use the context menu. Rankings still depend on content and technical SEO.

Why not paste JavaScript into the template instead?

Because template updates overwrite custom edits, and sitewide scripts are easy to mis-scope into the administrator. A system plugin is the durable approach.

Where do I download Right Click Disable?

From the Joomla Extensions Directory or the Infyways / JoomlaX download linked from that page. Try the live demo first.