Upgrading from Joomla 3.10 to Joomla 4 — a safe, step-by-step checklist for beginners

Quick answer: Will an automatic upgrade 'break' my site?

Short answer: not usually — but incompatible third-party extensions, outdated templates, or PHP mismatches are the most common causes of breakage. The Joomla core upgrade updates core files and database schema, but it does not automatically convert or fully guarantee third-party extensions will function under Joomla 4. The safest approach is to test the full upgrade on a staging clone and keep reliable backups so you can restore if needed.

What the core upgrade changes (and what it doesn't)

• The core upgrade updates Joomla core files and runs required database migrations for the core system.
• Third-party extensions generally remain installed but may become incompatible — they are not automatically rewritten for Joomla 4.
• Some extensions include their own update scripts; behavior varies by vendor and must be confirmed per-extension.

Common symptoms if an extension fails after upgrade

• Frontend errors such as blank pages, PHP warnings, or broken layouts where the extension displays.
• Backend problems including administration pages failing to load or login errors caused by plugin conflicts.
• Database errors if an extension relies on database structures that conflict with post-upgrade schema.

Practical examples: an unmaintained gallery extension might cause a blank frontend while the admin still loads; or a legacy payment plugin might trigger PHP fatal errors after the core update. These are avoidable by testing on staging and resolving incompatible items first.

Warnings: Do not run a live production upgrade without full backups and a tested staging upgrade. Avoid making large content edits on the live site during the upgrade window.

Preparation checklist before you touch the live site

Before you start any upgrade work, gather credentials, environment details, and make a plan. Treat this step as mandatory — missing information increases recovery time if things go wrong.

Files and data to record or copy

• Full filesystem copy: site root including /administrator, /components, /templates, /images and configuration.php.
• Database export (.sql) and a note of DB name, DB user, DB host and privileges.
• Text file listing installed extensions, their versions, and the active template name(s).

Credentials and environment notes

• Hosting panel (cPanel/Plesk) login, FTP/SFTP or SSH credentials, and Joomla administrator credentials.
• Record the current PHP version and enabled PHP modules (using phpinfo() or the hosting panel).
• Note any cron jobs, external services, payment gateways, or integrations that affect site behavior.

Checklist example: create backup-2026-05-XX.tar.gz (filesystem), backup-2026-05-XX.sql (database), configuration.php copy, extensions-list.txt, note PHP 7.4.33 and MySQL/MariaDB version.

Warnings: configuration.php contains live DB credentials — store backups securely. Do not leave backup archives in a publicly accessible webroot.

How to make reliable backups (files and database)

Make two independent backups and verify their integrity. If possible, store copies off-site (cloud storage, another server) to protect against host-level failures.

Backing up the database

• Use phpMyAdmin Export → save a .sql file (Quick or Custom). For large databases, use an SSH-based export when available.
• Verify the SQL file by opening the first few lines and checking for CREATE TABLE / INSERT statements.

Backing up files

• Compress the site root to a .zip or .tar.gz using the hosting file manager or SSH.
• Copy configuration.php separately and verify its permissions; do not expose it publicly.
• Keep backups out of the webroot and remove them from the server after downloading if you must keep only local copies.

Using backup extensions

Well-known backup extensions such as Akeeba Backup can create full site archives and installer packages. Even when using a backup extension, download and store the archive in a secure location and test that it restores correctly on a separate environment.

Practical examples: phpMyAdmin export (select DB → Export → Format: SQL → Save), or use a hosting control panel to compress files. For large sites, prefer server-side exports to avoid PHP timeouts.

Warnings: Large sites may exceed phpMyAdmin limits — use SSH/mysqldump or a backup extension. After restoring, ensure file ownership and permissions are correct for your hosting environment.

Create a safe staging environment and why it matters

Staging is the place to do risky work. Never run your first upgrade attempt on production.

Step sequence to create a staging copy

1. Create a staging location: a subdomain (a protected staging subdomain), a subdirectory, or a local development environment (XAMPP, Local, Docker).
2. Create a new database for staging and import your SQL dump.
3. Copy the filesystem into the staging folder and update configuration.php to point to the staging DB and base URL. Note: editing configuration.php must be done carefully — change only DB connection and live-site settings appropriate for staging.
4. Block search engines and restrict access (HTTP auth or IP restriction) so staging is not indexed or used in production.

Testing the staging site

• Verify front-end pages, admin login, and core functionality before attempting upgrades.
• Take a fresh backup of staging before running the upgrade attempt so you have a known-good snapshot.

Practical example: create a subdomain via cPanel, create a DB, import backup.sql via phpMyAdmin, copy files to /public_html/staging, update configuration.php DB settings, then visit a protected staging subdomain and confirm it matches production.

Warnings: disable cron jobs and payment gateways on staging to avoid duplicate emails or transactions. Secure configuration.php and remove any temporary files like phpinfo.php after checking.

Check PHP and server requirements (what to verify)

Joomla 4 requires a newer PHP and specific modules. Verify exact minimums in the official Joomla documentation before changing server settings. Always test PHP changes on staging first.

How to check PHP version and modules

• Create a temporary phpinfo.php file with a phpinfo() call on staging to view PHP version and enabled modules, or use your hosting panel's PHP info page.
• Check the command-line (CLI) PHP version if you run cron jobs or command-line scripts on the server.

When to change PHP version and how

• Many hosts allow you to select PHP per site or per folder in the control panel. Ask your host if you are unsure.
• After changing PHP on staging, verify that extensions and templates still work before applying the change on production.

Practical example: upload phpinfo.php to staging, open it in your browser and confirm the PHP version and presence of modules such as mbstring, json, curl, xml and zip.

Warnings: Changing PHP on production without testing can break extensions that rely on older behavior. Remove phpinfo.php when finished to avoid exposing server details.

Verify exact Joomla 4 minimum and recommended PHP versions against the official Joomla documentation before making production changes.

Inventory and compatibility check for extensions, templates and plugins

Create a complete inventory and check compatibility status for each installed item. Prioritize mission-critical features for deeper assessment.

How to list installed extensions and record versions

• Use Extension Manager → Manage to view installed extensions and copy names and version numbers into a spreadsheet.
• Note the active template(s) and any template overrides — templates are frequent sources of incompatibility.

Tools and resources for compatibility checking

• Check the Joomla Extensions Directory (JED) and vendor changelogs for Joomla 4 compatibility statements.
• Contact vendors when compatibility is unclear and ask for upgrade paths or planned support for Joomla 4.

Practical example: build a spreadsheet with columns: Extension, Type (component/module/plugin), Installed version, Joomla 4 compatible? (Yes/No/Unknown), Action (Update/Replace/Disable/Port).

Warnings: Extensions marked as 'no longer maintained' are high risk. Do not rely solely on third-party or community claims — verify vendor documentation.

Options for incompatible extensions: update, replace, disable, or custom fix

When an extension is incompatible with Joomla 4, follow a decision flow: update → contact vendor → replace → disable → port/rebuild. Choose the path based on the extension's importance and availability of maintained alternatives.

Update or patch

• Check vendor sites for updates and read changelogs for explicit Joomla 4 support.
• Apply and test patches on staging before running the core upgrade.

Replacement options

• Search JED for maintained alternatives and trial them on staging. Evaluate data migration needs.
• Plan how to move existing data (CSV export/import, component migration tools, or manual migration).

Disable and mitigate

• Temporarily disable non-critical extensions and test the site; document user-facing functionality loss and alternatives.
• When disabling, be aware that data may remain in the database; plan cleanup or migration if needed.

Custom porting or rebuild

• For custom extensions, request developer estimates to port to Joomla 4 APIs.
• As a last resort, rebuild the feature with maintained extensions or custom development.

Practical decision matrix: If extension has a Joomla 4 update → update and test. If unmaintained and critical → replace or hire a developer. If unmaintained and non-critical → disable and accept reduced functionality until you can replace it.

Warnings: Disabling an extension without migrating or cleaning its data can leave orphaned database tables. Avoid ad-hoc edits to extension code to force compatibility — this can create future maintenance problems.

Step-by-step: Testing and performing the upgrade on staging

Follow this sequence on staging to reduce surprises when you upgrade production.

Pre-upgrade checks on staging

• Confirm staging is a fresh clone with working backups.
• Update Joomla 3.10 to the latest 3.10.x releases and apply all updates for extensions that explicitly support 3.10 → 4 migration.
• Disable or remove extensions already identified as incompatible (document each change).
• Enable error reporting on staging to capture warnings during the upgrade process.

Running the upgrade

1. From Joomla Administrator, update Joomla 3.10 to the latest 3.10.x if required.
2. Use Extension Manager → Update or the Joomla Update component to upgrade to Joomla 4 and follow on-screen steps carefully.
3. Allow any database migrations to run; monitor the process and check logs for errors.

Post-upgrade validation checklist

• Confirm admin login and ability to save configuration.
• Open frontend pages, create and save an article, test forms and contact submissions.
• Test mission-critical extensions (payments, membership, SEO tools) and check server error logs for PHP errors.
• Take a new staging backup once the upgrade is confirmed successful.

Warnings: Do not attempt to migrate a site with unresolved critical incompatible extensions. Some templates may need Joomla 4-compatible versions; test templates and overrides thoroughly.

Verify the official Joomla upgrade guide for exact pre-upgrade and update sequencing before performing production upgrades.

If the upgrade fails: rollback and recovery steps

If the upgrade produces irreversible errors or an unusable site, restore the known-good backups and avoid further live edits. A clean rollback is usually faster and safer than attempting piecemeal repairs on production.

Restoring the database

• Use phpMyAdmin Import or the server's MySQL import tools to restore the saved .sql backup into the original database or into a newly created database referenced by configuration.php.
• Be cautious with partial DB backups — incomplete restores create mismatches and may require professional help.

Restoring files

• Unpack the filesystem archive into the site root and ensure correct file ownership and permissions for your hosting environment.
• Replace configuration.php with the backed-up copy and verify DB connection settings.

Common post-rollback checks

• Clear Joomla caches and any server caches (Varnish, Cloudflare) after restore.
• Check front-end and admin, and inspect PHP and web server error logs to confirm the site is operating normally.

Warnings: Restoring files without restoring a matching database (or vice versa) can produce a broken site. Keep backups matched by timestamp and avoid mixing states.

When to rebuild from backups or archive content

Sometimes an in-place upgrade is impractical. Rebuilding is often the right choice when many critical extensions are unmaintained or the site has accumulated complex, undocumented customizations.

Options for extracting content

• Export core content (articles, categories, contacts) via SQL or CSV export tools so content can be imported into a fresh Joomla 4 install.
• Use a backup extension that can create an installable package for a fresh install where possible, but verify compatibility of the installer with Joomla 4 before relying on it.

Planning a rebuild

• Map old features to modern, maintained extensions or to Joomla 4 native functionality.
• Prototype the rebuilt site on staging, import content, and validate design, SEO, and functionality before going live.

Warnings: Migrating only a DB often carries over obsolete extension tables and unused data. Rebuild projects usually require additional planning for SEO, URLs, and redirects to preserve search rankings.

When to call in professional help (and what to expect)

If key extensions are custom or you do not feel comfortable with backups, server access, or database imports, bring in a Joomla professional. Professionals can evaluate the upgrade on staging, provide costed plans, and execute complex porting safely.

What to prepare before contacting a developer

• A package containing: full backups (files + DB), extension inventory, template name and any overrides, staging access, and a prioritized list of features to preserve.
• Reproduction steps for site-critical features so the developer can verify fixes on staging.

Typical professional services and costs (guideline)

• Expect an evaluation fee or time-based estimate for diagnosing incompatible extensions and proposing fixes.
• Smaller fixes (single extension compatibility) usually cost less than full rebuilds; get a written scope, timeline, and rollback plan.

Warnings: Require staged work first and final approval before production changes. Ensure credentials are temporary or changed after the engagement for security.

FAQ

Conclusion

Upgrading from Joomla 3.10 to Joomla 4 is achievable with a safety-first approach: collect credentials, make reliable backups, clone to staging, inventory extensions and templates, resolve incompatibilities, test the upgrade on staging, and have a tested rollback plan. When in doubt or for complex setups, hire a Joomla professional to avoid extended downtime or data loss. Always verify version-specific server requirements and upgrade steps against the official Joomla documentation before making production changes.