Upgrading from Joomla 3.10 to Joomla 4: a practical, safety-first checklist for beginners

Quick answer: risks and the safety-first approach

If you need a short answer: yes, upgrading can break parts of your site if extensions, templates or custom code are incompatible. Most risks are avoidable by taking a careful sequence of steps: inventory your site, take a verified backup, create a staging copy, test the upgrade there, and make a rollback plan for the live upgrade.

What compatibility warnings usually mean (extensions, templates, overrides)

• Many warnings simply indicate an extension or template has not been declared compatible with Joomla 4. That is not the same as proven incompatibility, but it requires verification.
• Templates and template overrides are frequent break points because presentation code and some APIs changed between Joomla 3 and Joomla 4.
• Custom PHP code, small helper scripts or overrides may rely on deprecated Joomla APIs that behave differently under Joomla 4.

Practical example: a contact form extension not updated for Joomla 4 might stop accepting submissions after an upgrade. On staging the form page could throw a PHP error or silently fail to send emails.

Essential safety checklist (short)

1. Create a full files+database backup and verify it by restoring into staging.
2. Make a complete inventory of extensions, templates and custom code.
3. Test the entire upgrade on staging before touching the live site.
4. Plan a tested rollback method and a maintenance window for the live upgrade.

Warnings: Do not run an automatic upgrade on a live site without testing on staging and verifying backups. Assume custom code and template overrides might need manual fixes.

Overview: what changes between Joomla 3.10 and Joomla 4 (high level)

Joomla 4 is a modernization of the platform: it introduces an updated admin UI, modernized code, and changes in some internal APIs. These improvements can change how extensions and templates work. As a site owner, the key differences to understand are server requirements, admin interface changes, and API deprecations that could impact third-party code.

Supported PHP versions for Joomla 3.10 and Joomla 4 (verify before publishing)

The server PHP version matters because Joomla 4 requires a newer PHP baseline than many Joomla 3 sites used historically. Before you change PHP on production, confirm the exact minimum and recommended PHP versions for your target Joomla 4 release using official Joomla resources. Test PHP changes on staging first.

Practical example: a host using PHP 7.2 may run Joomla 3.10, but Joomla 4 might require PHP 7.4 or newer. Upgrading PHP on production without a staging test could cause extensions that are tied to older PHP behavior to fail.

Warning: Do not change production PHP versions without testing on staging and confirming compatibility with all extensions and custom code.

Step 1 — Inventory: list your site’s extensions, templates and custom code

Before you do anything, build a complete inventory of what your site uses. Knowing what extensions and templates exist, who provides them, and whether updates are available is the foundation of a safe upgrade.

What to record in your inventory

• Name of the extension or template
• Version installed
• Vendor or developer
• License type (commercial, free, custom)
• Whether a Joomla 4-compatible release is available (Yes / No / Unknown)
• Whether the extension stores critical site data and any notes about custom overrides or patches

How to export a list of installed extensions

Use the Extensions Manager in the Joomla admin to view installed items and copy them into a spreadsheet. If you are comfortable with databases, a simple query on the extensions table can export names and versions, but mark database queries for verification before running them.

Inventory example (text-style)

1. Component: com_contact | Version: 3.0.2 | Vendor: XYZ | Joomla 4 compatible? Yes | Notes: no custom overrides
2. Component: com_gallery | Version: 2.1 | Vendor: Abandoned | Joomla 4 compatible? No | Notes: stores images and metadata in custom tables
3. Template: mysite_tpl | Version: 1.5 | Vendor: Previous developer | Joomla 4 compatible? Unknown | Notes: Contains template overrides in templates/mysite/

Warnings: Do not assume an extension is compatible because it appears simple—check vendor notes or test in staging. Custom scripts outside of the Joomla folders can be missed; search for unusual directories or files that the previous developer may have added.

Step 2 — Prepare the environment: PHP, backups and a staging copy

Preparation is the most important part of a safe upgrade. This step explains how to verify server environment, make and verify backups, and create a staging copy for testing.

Verify server environment

• Check the PHP version and database engine on your host and plan to match or exceed Joomla 4 requirements on staging.
• Identify whether extensions require specific PHP extensions or settings.
• Ask your hosting provider about the best way to set PHP versions per site and whether you can clone the site into a staging plan.

How to create a full backup (files + database) and verify it

• Use a reliable backup method such as host snapshot tools or a well-known backup extension. If you reference a specific backup tool, verify the recommended workflow in that tool's documentation before publishing.
• Always include files and the full database export. Store backups off-site and keep multiple restore points.
• Verify a backup by restoring it to a staging location and confirming the site functions. A backup that cannot be restored is not a backup.

Setting up a staging site: hosted staging vs local environment

Hosted staging (a subdomain or a host-provided staging feature) is closest to production and is often easiest for beginners. Local environments (Laragon, XAMPP, Docker) give more control and are recommended if you or a developer will be debugging code. When restoring to staging, update configuration settings such as the database credentials and the configuration.php paths before testing.

Example checklist for staging preparation

1. Take a full files + DB backup from live.
2. Restore backup into a staging subdomain or local environment.
3. Update configuration.php, test database connection and site URL.
4. Password-protect staging and set noindex to avoid search engine indexing.
5. Set PHP on staging to the target Joomla 4-supported version and verify no fatal errors on load.

Warnings: Never test an unverified backup on live. Ensure staging is not indexed by search engines and is access-restricted. When changing PHP versions, do this in staging first to reduce risk.

Step 3 — Check compatibility: official tools and manual checks

Compatibility checks combine automated and manual steps. Use Joomla admin pre-update checks where available, consult the Joomla Extensions Directory (JED), and visit vendor changelogs and support notices.

Using Joomla core pre-update checks — where to find them

Joomla includes pre-update checks that can surface basic server issues and flag extensions that are not marked as compatible. Verify the exact names and navigation of these admin tools in the official Joomla docs before relying on them.

Checking vendor pages and the Joomla Extensions Directory for compatibility

• Search for the extension in the JED and read compatibility badges, release notes and changelogs.
• If the JED listing is unclear, check the vendor's website or contact support for a definitive compatibility statement.
• Mark each extension as: Compatible, Incompatible, or Unknown. Prioritize fixes for any extension marked Incompatible or Unknown that affects critical functionality.

Practical walkthrough: run the admin pre-upgrade check on staging, export or copy the list of flagged items, then open vendor pages for your top 5 critical extensions (forms, login, payment, SEO, user management) to confirm their Joomla 4 roadmap.

Warnings: A compatibility flag often means the extension is 'not marked as compatible' rather than 'known incompatible'. Testing on staging is still required.

Step 4 — Handling incompatible extensions and plugins

When you find an extension with no Joomla 4 update, you have several options. Choose based on how critical the extension is and how much data or custom behaviour it controls.

Options for abandoned or commercial extensions with no update

• Check for maintained alternatives in the JED and evaluate migration effort and data portability.
• Export data from the old extension where possible (CSV, SQL exports) before uninstalling or replacing it.
• Contact the vendor to ask about paid updates or migration tools; keep records of vendor responses.
• Hire a developer to port or patch the extension if it is business-critical and replacement is not feasible.

What to do about templates and custom overrides

• Test the upgraded site with a default Joomla 4 frontend/admin template on staging. If the site works with default templates, the problem likely lives in your template or overrides.
• Document template overrides and migrate them one at a time, testing after each change. Consider moving to a modern, maintained template if the existing theme requires extensive refactoring.

Practical scenario: If an image gallery extension is abandoned, export image metadata and files, install a maintained gallery extension on staging, and import the data. Keep a readonly copy of the old gallery data tables for reference.

Warnings: Uninstalling an extension without exporting its data can cause irreversible data loss. Preserve original files and database tables before attempting replacements.

Step 5 — Run the upgrade on staging and verify site functionality

Now that staging is prepared and incompatible items are identified, perform the Joomla core upgrade on your staging site and run a structured test plan to verify key user and admin journeys.

Testing key site paths: forms, login, ecommerce, menu structure

Create a test plan that exercises the highest-value paths on your site. For example:

• Homepage loads and navigation renders correctly
• Public forms submit and send emails
• Login/registration works for both admin and regular users
• Ecommerce checkout completes using a sandbox gateway
• Back-end tasks such as publishing an article, managing users and cron-like jobs work

Common post-upgrade fixes

• Clear Joomla caches and any host-level caches, then re-test.
• Rebuild menus and re-check SEF/SEO URLs.
• Review ACL and permissions to ensure group rights are intact.
• Check logs for PHP errors or stack traces and map them back to extensions.

Staging test checklist example

1. Homepage load time acceptable and no fatal errors.
2. Contact form submits and email received in inbox.
3. Admin login and content creation possible.
4. Payment sandbox processes complete a test order.
5. Search and menu links behave as expected.

Warnings: Some issues only appear in high-traffic conditions. If your site is high-traffic, consider load testing or staging that simulates production traffic patterns.

Step 6 — Plan and execute the live upgrade

When staging tests are green, plan the live upgrade carefully. Schedule during a low-traffic window, notify stakeholders, and be ready to rollback quickly if something critical fails.

Checklist for the live upgrade

1. Create a final, verified backup of files and database immediately before the upgrade.
2. Put the site into maintenance mode or use measures to prevent new transactions (for ecommerce sites consider read-only or draining strategies).
3. Set the server PHP to the required version if necessary and confirmed on staging.
4. Run the same upgrade steps used in staging and monitor logs in real time.
5. After upgrade, clear caches, run post-upgrade test checklist and only then remove maintenance mode.

How to perform a safe rollback if necessary

The safest rollback is restoring the verified backup snapshot you created before the upgrade. Test the restore process on staging ahead of time so you know the time it takes and any host-specific considerations. If the site processed new data during the upgrade, note that restoring the old database may drop new records; plan for that possibility.

Timing example: 00:00 set maintenance mode, 00:05 final backup, 00:15 start upgrade, 00:45 run smoke tests, 01:00 remove maintenance mode if green.

Warnings: A live rollback may require database downtime to avoid data inconsistencies. Hosts may cache PHP settings or opcache; clear host-level caches when switching PHP versions.

Fallback options: rollback, restore or rebuild

If the upgrade fails or produces unacceptable regressions, choose a fallback strategy based on severity and business need.

Fallback strategies

• Immediate full rollback: restore the pre-upgrade files + DB snapshot and reopen the site.
• Partial restore: restore only the database or only files when it is safe and understood.
• Rebuild or replace components: for persistent compatibility issues, replace abandoned extensions with modern alternatives and migrate data.

Practical example: If checkout is broken after upgrade, restore the DB snapshot taken before upgrade, test checkout in staging, and then reattempt a controlled live upgrade after fixes.

Warnings: Partial rollbacks can be risky if schema changes are involved. When in doubt, prefer a full restore of files and DB, and ensure no manual edits were made to the live site during the upgrade window.

When to call a developer or migrate to a new site

Some upgrade problems are best handled by a developer or by planning a migration to a rebuilt site. Hire help if a critical extension is abandoned and contains business-critical logic or if the site uses extensive custom code.

Signs that a rebuild or professional help is the right choice

• A large number of incompatible third-party extensions with no updates.
• Heavy custom code tightly coupled to Joomla 3 APIs.
• An outdated template requiring comprehensive refactoring to work under Joomla 4.

Practical guidance: When hiring a developer, prepare staging access, full backups and documentation of your inventory to reduce the time they need and lower costs. Factor in vendor and community response times into your timeline.

Resources and next steps

Before you start, gather authoritative resources and commit to a short plan. Verify any official URLs before taking action.

Next-actions checklist

1. Create a full backup and verify a restore on staging.
2. Complete an inventory of extensions, templates and custom code and mark critical items.
3. Set up a staging environment and configure PHP to match the target Joomla 4 requirement.
4. Run compatibility checks and contact vendors for unclear extensions.
5. Perform the upgrade on staging, run tests, and document fixes before scheduling the live upgrade.

Suggested one-week plan: Day 1 inventory and backups; Day 2 restore to staging; Day 3 compatibility checks and vendor outreach; Day 4 staging upgrade attempt; Day 5 fix and re-test; Day 6 schedule and perform live upgrade; Day 7 monitor and finish post-upgrade tasks.

FAQ

Will my site 'blow up' if I try the automatic upgrade?

Upgrading carries risk, but most problems are avoidable with staging, verified backups and pre-upgrade checks. The most common failure modes are incompatible extensions, template breakage, and custom code errors. Do not run an automatic upgrade on live without staging verification.

How can I tell which extensions will work in Joomla 4?

Use the Joomla admin pre-update checks, consult the Joomla Extensions Directory and extension vendor changelogs, and test the extension on a staging copy. If compatibility is unclear, contact the vendor or test directly in staging.

Can I downgrade PHP to help with the upgrade?

Changing PHP versions can help replicate production in staging, but avoid downgrading live servers. Make PHP changes in staging first and verify extension compatibility. Confirm the exact supported PHP versions from official Joomla resources before changing PHP on production.

What if an important extension has no Joomla 4 update?

Options include finding a maintained replacement, exporting and migrating data, hiring a developer to port the extension, or building a custom bridge. Consider the cost, data migration risk, and long-term maintenance needs when choosing.

How long will the upgrade take?

A simple site might be upgraded and tested in a few hours. Complex sites with many extensions or ecommerce integrations can take days or weeks to test and fix. Allow time for staging testing and troubleshooting.

Conclusion

A cautious, staged approach is the best way to protect your live Joomla site during an upgrade: inventory your extensions, create and verify full backups, test the upgrade on staging, and have a tested rollback plan. If you encounter abandoned or complex extensions, evaluate replacements or hire a developer. Always verify step-specific technical details against the official Joomla documentation before performing changes in production.