Blog

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. 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. 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

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.

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

What you see	Usual cause	Fix
White screen or 500 error right after upgrading	A PHP fatal error in an extension, template, or .htaccess	Read the host error log and administrator/logs/joomla_update.php, then disable the extension named there. Don’t click Update again.
Class "JTable", "JFactory", "JPlugin" or "JText" not found	The backward compatibility layer is off. On Joomla 6, that’s Backward Compatibility 6 or its Classes Aliases setting	Enable the plugin (using SQL if you’re locked out), then find and update the extension still using the old class names.
Class "JRequest" not found	Removed in Joomla 4; no compatibility plugin restores it	The extension code has to be rewritten to use the application input object.
“Unknown column” or “table doesn’t exist”	A database schema step didn’t finish	System → Maintenance → Database → Update Structure.
The next major version never appears	Update channel is still Default, or PHP is below the minimum	Switch to Joomla Next and meet the PHP minimum for the target version.
Unstyled site, modules missing	A Joomla 3 template or overrides	Switch to Cassiopeia to confirm, then update or replace the template.
Homepage works but every other URL gives a 404 or 500	.htaccess or URL rewriting mismatch	Rename .htaccess, turn off URL rewriting, rebuild from htaccess.txt, then re-add your custom redirects (mod_rewrite 500 fix).
Login loop	Session table, cookie domain, or $live_site setting	Empty #__session and confirm the site URL in Global Configuration.
Download failed, out of memory, or the progress bar stalls	Updater transport or server limits, not compatibility	Raise the memory and time limits, or use Upload & Update. See how to fix Joomla update errors.

For recovery SQL, schema repair when the Database screen shows nothing, and the full Joomla 6 removals list, use our Joomla upgrade issues runbook.

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.

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.

The Joomla generator meta tag is a single line in the HTML head, <meta name="generator" content="Joomla! - Open Source Content Management">. Joomla adds it in the document class. There is no switch for it in Global Configuration on Joomla 3, 4, 5, or 6. Remove it with setGenerator('') before the head is rendered, or with a system plugin. An empty string omits the tag. null is the wrong value and can fatal on PHP 8.

The tag does not contain your version number. Removing it does not change Google rankings. It only drops one fingerprint. RSS feeds, the administrator login page, and administrator/manifests/files/joomla.xml still identify the CMS unless you handle those separately.

What you will learn

• The exact tag Joomla prints, and why it is not a version number
• How to see it in HTML and in RSS
• The template one-liner, and why it disappears on the next template update
• Why setGenerator(null) is unsafe
• What still gives the site away after the tag is gone

What the tag is

HTML’s generator meta names the software that built the page. Joomla sets that string when it creates the HTML document. It is not read from a menu item, not stored in the database, and not a language string you can override. The same property is written into RSS and Atom as a <generator> element.

On current Joomla 3.10, 4, 5, and 6 the content is only:

<meta name="generator" content="Joomla! - Open Source Content Management">

Very old releases (Joomla 1.5 and early 2.5) put the version in that string. That stopped years ago. If a scanner claims it learned “Joomla 3.9.28” from this meta tag, it learned it somewhere else.

What removing it does, and what it does not

Claim	Reality
Hides the Joomla version from attackers	The version is not in this tag. It is in administrator/manifests/files/joomla.xml and in the administrator’s System Information screen
Improves Google rankings	No. Google does not use meta name="generator" as a ranking signal
Hurts SEO	No, as long as you do not also delete the robots meta tag
Makes the site invisible to scanners	No. /media/system/js/core.min.js, /administrator/, and Cassiopeia paths still look like Joomla
Removed by a Joomla or template update if you only edited index.php	Yes. A template update replaces that file
Removed from RSS if you only call setGenerator inside <head> after the head include	No. Feeds never render that head block

Treat this as housekeeping, not as a security patch. An outdated Joomla site with the tag removed is still outdated. Update path: how to update Joomla.

Step 1: See the tag before you change anything

1. Open the public homepage.
2. View source (not only the inspector). Search for generator.
3. You should find the meta line above. Joomla 3 often writes it self-closed (/>). Joomla 4 and newer usually do not.
4. Open the feed: add ?format=feed&type=rss to the site URL, or use the RSS link in the page. Search for <generator>. The same sentence is there.
5. Optional: open /administrator/ and view source. The login page carries the tag too.

If the line is missing already, a plugin or the template is stripping it. Do not add a second strip until you know which one.

Step 2: Prefer a plugin over a template edit

A system plugin runs on every HTML and feed response and survives template updates. Infyways publishes Remove Meta Generator for this. Version 1.4 is for Joomla 4, 5, and 6. It clears or replaces the generator on the public site, can clean RSS and Atom, and can drop the X-Powered-By header. It does not touch the administrator. Listing: Joomla Extensions Directory.

1. Install the zip and enable System – Remove Meta Generator.
2. Set generator to remove, or replace it with your own brand text if you want a tag with different content.
3. Leave the robots option alone unless you have a reason to change indexing. Deleting meta name="robots" can drop a noindex you still need, or strip a normal index directive.
4. Clear Joomla cache and any CDN cache.
5. View source on the homepage and on one article. Then check the RSS feed.

Joomla 3 is not a target of the 1.4 build. On 3.10 use the template line in the next step, or stay on a plugin build that still lists Joomla 3.

Step 3: Or set an empty generator in the template

This works on Joomla 3, 4, 5, and 6. In templates/YOUR_TEMPLATE/index.php, before <jdoc:include type="head" /> and before <jdoc:include type="metas" />:

<?php
$this->setGenerator('');
?>

Use an empty string. Do not pass null. The document API types setGenerator as a string. On PHP 8 a null argument becomes a fatal once that type is enforced. An empty string is what makes the renderer skip the tag. Joomla only prints the meta when getGenerator() is non-empty.

Put the line at the top of the file if you are unsure. Code after the head include is too late: the meta block has already been built.

A template update overwrites index.php. Put the line in a child template, or use the plugin. Do not edit libraries/src/Document/HtmlDocument.php or libraries/joomla/document/html/html.php. The next Joomla update puts the tag back and can break the core file.

Step 4: Cover feeds, not only the homepage

The template line never runs for format=feed. A plugin event does. This is the body of a system plugin method. On Joomla 3.8 and newer, and on 4, 5, and 6, Joomla\CMS\Factory is available without the compatibility plugin:

public function onBeforeRender()
{
    $app = Factory::getApplication();

    if (!$app->isClient('site')) {
        return;
    }

    $doc = $app->getDocument();
    $type = $doc->getType();

    if ($type !== 'html' && $type !== 'feed') {
        return;
    }

    $doc->setGenerator('');
}

onBeforeRender is early enough for HTML and for RSS. onBeforeCompileHead is HTML-only, so a head-only hook leaves the feed element in place. Skip non-HTML types such as JSON and raw so you do not touch component output that is not a document head.

On Joomla 3.7 and older, swap Factory::getApplication() for JFactory::getApplication() and isClient('site') for isSite().

Step 5: Confirm it is gone, including cache

• View source on the homepage, an article, and a category blog.
• Search for name="generator". No match means the Joomla tag is gone. A match with different content means a template or extension hardcoded its own tag. setGenerator will not delete a string that was echoed by hand. Search the template for generator and remove that line.
• Open the RSS URL and confirm there is no <generator>Joomla! element, if you used the plugin or onBeforeRender.
• Clear System → Maintenance → Clear Cache, then the host cache or Cloudflare, or you will keep seeing the old HTML.
• Check /administrator/ only if you intended to change it. The JoomlaX plugin leaves admin pages alone on purpose.

Other fingerprints people confuse with this tag

Signal	What it is	Removed by setGenerator?
meta name="generator"	HTML fingerprint, no version	Yes, if you set an empty string in time
RSS <generator>	Same property, feed renderer	Only if the call runs for feed documents
X-Powered-By: PHP/x.y	Server header, not Joomla’s meta tag	No. Turn it off in PHP or in the plugin’s header option
administrator/manifests/files/joomla.xml	Core manifest, includes the version	No. This file is the real version leak
/media/system/js/core.min.js and /administrator/	Paths and the login screen	No
meta name="robots"	Indexing instructions	Should stay. Unrelated to the generator

Blocking the manifest is a hosting or Admin Tools job, not a meta-tag job. Hiding files is still weaker than installing updates. If the site is on Joomla 3, plan the move instead of collecting hide-the-CMS tricks: Joomla upgrade services.

SEO

Removing the generator tag does not move rankings. Google indexes the visible page, links, and a handful of meta tags it actually reads (description, robots). generator is not one of them. More on what does matter: Joomla SEO.

The change that does hurt SEO is a plugin option that deletes every robots meta. Leave that control on “leave” unless you are setting a specific policy, such as index, follow on purpose.

Key takeaways

1. The tag says Joomla. It does not say which version.
2. There is no Global Configuration checkbox. Use setGenerator('') or a plugin.
3. Never pass null. Never edit files under libraries/.
4. A template edit dies on the next template update and never touches RSS.
5. Removing the tag does not change SEO. Do not remove the robots meta while you are there.
6. Update Joomla. Hiding the tag is not a substitute.

Frequently asked questions

How do I see the Joomla generator meta tag?

View source on the homepage and search for generator. The default content is Joomla! - Open Source Content Management. The same text is in the RSS <generator> element.

How do I remove the Joomla meta generator from the head?

Call $this->setGenerator('') in the template before the head include, or enable a system plugin that does it on onBeforeRender. Empty string, not null.

Will removing the generator tag affect SEO?

No. Google does not use that meta tag for ranking. Leave meta name="robots" in place.

Does this tag reveal my Joomla version?

Not on Joomla 3.10, 4, 5, or 6. The version is in administrator/manifests/files/joomla.xml, not in the generator meta.

Does Joomla 5 or 6 still add the tag?

Yes. There is still no core switch. The same setGenerator('') call works, or use Remove Meta Generator 1.4.

Will a Joomla update put the tag back?

A core update does not restore a plugin setting. A template update does restore index.php if you edited the parent template. Core file hacks under libraries/ are overwritten.

Does the template line remove it from RSS?

No. Feeds do not load index.php. Use onBeforeRender or a plugin that cleans feed output.

Is setGenerator(null) safe on PHP 8?

No. Pass an empty string. Null does not match the string argument and can fatal.

Can I remove it without editing files?

Yes. Install Remove Meta Generator, enable it, clear cache, and view source.

Call to a member function setState() on null (also “on bool”, “on boolean”, or “on a non-object”) means Joomla tried to call setState() on a model that was never created. getModel(), JModelLegacy::getInstance(), or createModel() returned false or null, and the next line did not check. This is not a session error, and clearing the cache does not create the missing class.

The line that dies is almost always a content module or an old component controller preparing a list query. The fix is to load the model, or to update or disable the extension named in the stack trace.

What you will learn

• What setState() does on a Joomla model, and why this is not React and not the session
• Why the same bug is worded three different ways on PHP 7 and PHP 8
• How to read the file path and name the extension in one minute
• The Joomla 3 include-path failure, and the Joomla 4, 5, and 6 bootComponent() pattern
• What to do when the administrator will not open

What the error actually means

Joomla list screens do not read $_GET inside the query. They park filters on the model first:

$model->setState('filter.published', 1);
$model->setState('list.limit', 5);
$model->setState('params', $params);
$items = $model->getItems();

setState() only exists on a model object (ListModel, BaseDatabaseModel, and the older JModelLegacy). If $model is false or null, PHP stops with a fatal error before getItems() runs. The message changes with the PHP version, not with the bug:

What PHP says	What $model is	Typical PHP
on a non-object	false from getInstance() or getModel()	PHP 5
on boolean	Same false	PHP 7
on bool	Same false	PHP 8 and newer
on null	createModel() found nothing	PHP 7.0+ and Joomla 4+

A different sentence, Call to undefined method ... setState(), means you do have an object, but it is the wrong class. Do not mix those up. This article is only the null or false case.

This is not the session, and it is not React

Session data in Joomla is $app->setUserState() and getUserState(). Deleting files in /tmp, logging out, or emptying #__session does not make getModel() return an object. Do that only when the error text actually names the session handler.

React’s setState() is a JavaScript method on a component. A PHP fatal in a .php file under modules or components has nothing to do with a React build. If the stack trace is a .js bundle, you are in a different app that happens to be hosted beside Joomla.

Where it breaks

Path in the error	What failed	Fix
modules/mod_articles_latest, mod_articles_category, mod_articles_news, mod_related_items	The articles model was not booted before setState('params')	Use the core helper pattern below, or replace a cloned module
components/com_SOMETHING/controller.php or controllers/cpanel.php	$this->getModel() returned false, then the controller called setState anyway	Update that component. Pass the model name. Check the return value
administrator/components/com_SOMETHING	Same failure, backend only	Disable that admin component. The public site can stay up
libraries/legacy/controller or libraries/src/MVC/Controller	Core ran. The component in the URL did not provide a model	Read option=com_... in the URL. Fix that extension, not the library
templates/YOUR_TEMPLATE/html	An override copied an old helper	Compare it with the current core file and drop the stale copy

The classic core case was Joomla 3.5.0: mod_related_items/helper.php line 44 called setState() on false because com_content models were not on the lookup path. That was fixed in 3.5.1. The report is still the best illustration of the bug: Related Articles module fatal error. Third-party modules still copy the broken pattern.

Step 1: Get the file and the line

1. If the page is a blank 500, open the host PHP error log or administrator/logs/. The fatal is one line: message, file, line number.
2. On a staging copy you can set Global Configuration → Server → Error Reporting to Maximum. Turn it off again on production. Do not leave display_errors on a public site.
3. Copy the first fatal only. Later errors are fallout.
4. A white page with no setState text may be .htaccess instead. Check that only after the log is silent. Guide: Joomla 500 on mod_rewrite.

Step 2: Confirm the variable is empty

Open the file at the line number. You want a call shaped like one of these:

• $model->setState(
• $this->getModel()->setState(
• $defaultModel->setState(

Look up three to ten lines. The assignment is getInstance, getModel, or createModel. There is no if (!$model) before setState. That missing check is the crash. Adding a return when the model is empty stops the fatal. It does not by itself bring the module back. You still have to make createModel succeed.

Step 3: Name the extension from the path

• mod_ prefix: a module. Unpublish that module to confirm the homepage returns. System → Manage → Extensions, or published = 0 on that row in #__modules if you cannot log in.
• com_ prefix: a component. The menu item or the URL option= is what triggers it. Note the folder name before you disable anything.
• plg_ or plugins/: a plugin. Rename that plugin’s folder over FTP if the administrator is already dead.
• Path contains libraries/joomla or libraries/src and your Joomla version is current: core is the messenger. The broken model belongs to the component in the request.

Take a backup before you rename folders or edit PHP. Method: how to backup a Joomla website.

Step 4: Load the articles model the way core does now

On Joomla 4, 5, and 6, article modules boot the component, then set state. This is the current core pattern in Latest Articles:

$model = $app->bootComponent('com_content')
    ->getMVCFactory()
    ->createModel('Articles', 'Site', ['ignore_request' => true]);

if ($model === null) {
    return [];
}

$model->setState('params', $app->getParams());
$model->setState('filter.published', 1);
$model->setState('list.limit', (int) $params->get('count', 5));

$app is Factory::getApplication(). ignore_request stops the model from reading the page URL as its own filters, which is what you want inside a module. Core reference: ArticlesLatestHelper.php.

If createModel still returns null, com_content is missing, half-updated, or the model name is wrong. Reinstalling random core files is not the first move. Confirm components/com_content exists and that System → Maintenance → Database shows no schema errors. A partial update leaves new PHP calling old tables, or the reverse. Update path: update Joomla and fix update errors.

Step 5: Fix the Joomla 3 version of the same bug

Joomla 3 will not boot a component. You add the model folder, then ask for the class prefix ContentModel:

JModelLegacy::addIncludePath(
    JPATH_SITE . '/components/com_content/models',
    'ContentModel'
);

$model = JModelLegacy::getInstance(
    'Articles',
    'ContentModel',
    array('ignore_request' => true)
);

if (!$model) {
    return array();
}

$model->setState('params', $params);

The file on disk must be components/com_content/models/articles.php and the class must be ContentModelArticles. A renamed class returns false from getInstance, and the next setState is this fatal.

Do not paste the Joomla 3 block into Joomla 4, 5, or 6. JModelLegacy is legacy. On current Joomla the failure mode changes: either the class is missing (see class not found after an upgrade) or getInstance returns false and you are back to setState() on bool. Use bootComponent().

Step 6: Update or disable the extension in the trace

If the file sits in a commercial component, you cannot invent its model name from the articles example. The controller is calling $this->getModel() with no name, the default model file is gone or not autoloaded after a Joomla 3.10 or Joomla 4 hop, and setState runs on false. That is an extension bug.

• Update it to a build that lists your Joomla major.
• If there is no update, disable it and unpublish its modules and menu items.
• Do not edit libraries/ to hide the message. The next core update overwrites the library and the fatal returns.
• A template override of a module helper is a copy. Delete the override and let the current module file run. Then retest.

Major-version breakage of this kind is covered in Joomla upgrade issues. Hop order still matters. A Joomla 3 controller will not start loading models correctly just because the site folder was copied onto Joomla 5.

Step 7: Clear cache after the page renders

Module HTML is often cached. A cached fatal, or a cached empty module, can linger after you fix the PHP. Clear it only once the uncached page works:

1. System → Maintenance → Clear Cache, or the cache button on the module.
2. Clear the host or CDN cache if the HTML is stored there.
3. Reload the page that crashed. The log line for setState should be gone.

If you clear cache first and the model is still null, the error comes straight back. Cache was never the cause.

Step 8: Get the administrator back

1. Read the log. If the path contains /administrator/components/com_ or /plugins/, rename that one folder via FTP or the host file manager. Joomla skips an extension whose folder is missing.
2. If a site module crashes every admin page because it is assigned to the admin menu, unpublish it in #__modules (published set to 0). Match module to the mod_ name from the log.
3. Leave com_content, com_users, and com_login in place. Renaming those locks you out for a different reason.
4. When the administrator loads, update or uninstall the extension properly, then restore the folder name only if you still need it.

What a correct call looks like

Core always sets state after it knows the model exists. The states you will see in article modules are the query, not user session keys:

• params: component or module parameters
• filter.published, filter.category_id, filter.access, filter.language, filter.featured
• list.start, list.limit, list.ordering, list.direction

If your code sets those on a model that failed to load, fix the load. If your code sets them on $app, you wanted setUserState() and you are in the wrong API.

When to stop patching the module

Stop if any of these are true:

• The trace names a component you cannot update, and the site still runs Joomla 3
• Several modules fatal with the same createModel null after a half-finished upgrade
• You already renamed folders and you are not sure which ones the business needs

Infyways runs those repairs and version jumps from $149, with a compatibility audit within 12 hours. Start at Joomla Upgrade Services.

Key takeaways

1. setState() on null or bool means the model object was never created.
2. It is not the session, not React, and not fixed by emptying /tmp.
3. The file path is the extension name. Start there.
4. Joomla 4, 5, and 6 load article models with bootComponent('com_content') and createModel('Articles', 'Site').
5. Joomla 3 needs addIncludePath plus ContentModelArticles. Check getInstance before setState.
6. Clear cache after the page renders, not before.

Frequently asked questions

What does Call to a member function setState() mean in Joomla?

PHP called setState() on null or false. In Joomla that value was supposed to be a model from getModel(), getInstance(), or createModel().

Is this a session or login error?

No. Session storage uses setUserState(), which is a different method. Logging out or deleting /tmp does not load a missing model.

Why does it say on bool on one site and on null on another?

Same failure. getModel() and getInstance() return false, so PHP 8 says “on bool”. createModel() returns null, so PHP says “on null”.

Which file should I open?

The file and line in the error. That line is the setState call. The extension folder in that path is what you update or disable.

Will Clear Cache fix it?

No. Clear cache only after the model loads, so Joomla does not keep serving a cached copy of the crash.

Does Joomla 5 or 6 still use setState()?

Yes. Article modules still call $model->setState() after createModel('Articles', 'Site'). The method is fine. A null model is not.

Can I fix it by reinstalling Joomla core?

Only when the trace points at a core file that does not match a stock copy of your version. If the path is a third-party component, reinstalling core leaves the bug in place.

The administrator is a white screen. How do I get in?

Rename the plugin or admin component folder named in the log. Do not rename com_login or com_users. Unpublish a site module from #__modules if that module is what crashes.

Who can fix setState() fatals across an upgrade?

Infyways traces the model load and finishes the version jump when the extension has no update. Request a Joomla upgrade audit.