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
- Open phpMyAdmin from your hosting control panel and select the Joomla database.
- Select the
#__userstable and open the Export tab. - Choose CSV (or SQL if you’re moving to another database) and download the file.
- Repeat for
#__user_usergroup_mapif you need group memberships, then join the data in a spreadsheet.
Importing with phpMyAdmin
- Take a full backup of the site and database first.
- Prepare a CSV whose columns exactly match
#__users, with unique usernames and emails. - Import it into
#__usersusing phpMyAdmin’s Import tab. - Add matching rows to
#__user_usergroup_mapso every user belongs to at least one group (usually Registered). Without a group, the account won’t behave like a normal user. - 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 asprofile_phoneorprofile_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 |
| 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
- Back up both sites.
- On the old site, export users with core fields, groups, profile data and custom fields, and choose include hashed passwords.
- On the new site, create the same user groups and user custom fields, so the names match.
- 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.
- Validate first, fix any errors, then import and check the log.
- 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
- Back up first. See how to back up a Joomla website.
- Test on staging with a small, representative batch before the full file.
- Clean the source file: remove duplicates, fill required fields and fix invalid emails.
- Create groups and custom fields first so mapped values have somewhere to go.
- Choose the import mode on purpose. Add New Only is the safest default.
- Treat exports as sensitive. Exclude passwords unless you’re migrating, store files securely and delete them when you’re done.
- 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.