Joomla Update in Joomla
Keeping Joomla up to date is the single most important thing you can do for the security of your site. A new release fixes bugs, closes security holes, and adds features. Joomla makes the whole job a one-click task with a dedicated core component. It checks for a new version, runs a safety check first, downloads the package, and replaces the files for you. That component is com_joomlaupdate, and you reach it from System → Update → Joomla.
This article explains how the Joomla Update component really works. It covers the basics for website owners, the day-to-day update screens for administrators, and the technical details for developers: the pre-update check, the update channels, the new automated updates in Joomla 6, the install pipeline, the database tables, and the REST API.
One component, one button, and the safety net that keeps the whole CMS current.
The goal is simple: help you understand com_joomlaupdate well enough to update Joomla safely and confidently, and to fix it when an update will not run.
1. The Basics
1.1 What com_joomlaupdate Is
com_joomlaupdate is the core Joomla component that updates Joomla itself: the CMS files, the database schema, and the bundled core extensions. It is one of the most important pieces of the backend, because an out-of-date Joomla is the most common way a site gets hacked.
It is itself an extension (a component named com_joomlaupdate), and it is marked protected, so you cannot remove it by accident. It can even update itself: before a big upgrade, it checks whether a newer version of the update component is available and installs that first.
com_installer updates your add-ons. com_joomlaupdate updates the CMS. They look similar but they are two different components.
1.2 Where to Find It
The component lives under the System menu in the administrator:
System
└─ Update
└─ Joomla (com_joomlaupdate)The URL is index.php?option=com_joomlaupdate. You also meet it through the update notification on the home dashboard (Control Panel): a colored message that tells you a new Joomla version is ready.
1.3 Who Can Use It
Updating Joomla means replacing the code that runs your whole site, so the component is locked to the highest permission level. Only a Super User (a user with the core.admin right) can open the screens and run an update. Every sensitive action checks core.admin in code and refuses anyone else. This is deliberate: a user who can update Joomla can effectively change any file on your server.
2. The Joomla Update Screen
2.1 What You See
When you open System → Update → Joomla, the component checks for a new version and shows one of a few states. Each state is a different layout of the same view:
| State | What it means |
|---|---|
| Update available | A newer version exists; you see the version number and an Install the Update button |
| Up to date | You run the latest version; you may still Reinstall the current core files |
| Component update first | The update component itself must update before the CMS; a self-update runs first |
| Upload & Update | A tab to upload a package by hand when the online check cannot reach the server |
2.2 The Two Ways to Update
The component offers two paths to the same result:
- Live Update: Joomla downloads the package itself from the official update server and applies it. This is the normal, one-click route.
- Upload & Update: you download the package from joomla.org yourself, upload the
.zip, and Joomla applies it. Use this when your server cannot reach the update server, or to install a specific package.
2.3 The Reinstall Option
When you are already on the latest version, the screen still offers a Reinstall button. This downloads the same version again and overwrites the core files. It is a quick, safe repair for a site whose core files got corrupted, half-overwritten, or accidentally edited. It does not touch your content or your extensions.
Back to top3. The Pre-Update Check
3.1 Why It Exists
An update can fail for reasons that have nothing to do with Joomla: an old PHP version, a missing PHP extension, or a third-party add-on that is not ready for the new release. The Pre-Update Check tab runs these tests before you click Install, so you fix problems on a working site instead of a broken one.
3.2 Environment Checks
The first part checks your server against the requirements of the target version:
- PHP version: is your PHP new enough for the version you are about to install?
- Required PHP extensions: modules such as
zip,gd, andjsonthat Joomla needs. - Database type and version: is your MySQL or MariaDB supported?
- Recommended PHP settings: values like
output_bufferingthat should be set a certain way.
A red row is a blocker: fix it before you update. A yellow row is a recommendation: the update will run, but the setting is not ideal.
3.3 Extension Compatibility
The second part is the most useful. It reads the list of your installed third-party extensions and asks the Joomla update server whether each one has a version compatible with the Joomla release you are targeting.
For each non-core extension:
→ look up its compatibility tag on the update server
→ "Compatible" green - a matching version exists
→ "Update required" yellow - update the extension first
→ "Unknown/none" grey - no information; check with the developerThis does not update the extensions for you. It tells you which ones to update first, so they keep working after the core jumps to a new major version. Always clear this list before a major upgrade.
Back to top4. Running a Core Update
4.1 The Safe Order
A clean core update follows the same steps every time. Do them in order:
1. Back up the site (files + database)
2. Open System → Update → Joomla
3. Read the Pre-Update Check; fix every red row
4. Update incompatible extensions first
5. Click "Install the Update"
6. Wait for the "complete" screen
7. Check the front end and the backendThe backup in step 1 is your real safety net. The component reminds you to make one, but it does not make it for you.
4.2 What Happens When You Click Install
Behind the one button, the live update runs a fixed sequence of controller tasks. You can see them flash by in the URL or the progress bar:
download → fetch the package from the update server, verify its checksum
install → extract the package into place
finalise → run the migration: update files, run SQL, run the update script
cleanup → remove the temporary package and restore files, show "complete"If a step fails, Joomla stops and reports the error rather than leaving you half-updated. The component writes a dedicated update log (Update) so you can see exactly where it stopped.
4.3 The Backup Reminder
Before the update starts, the component shows a checkbox reminding you that you have a recent backup. This is the backupcheck option at work. It does not verify that a backup exists; it only asks you to confirm. Treat it as a prompt to actually run your backup tool first.
5. Update Channels and Stability
5.1 The Update Source
com_joomlaupdate does not guess where updates come from. The Update Source option in the component Options decides which channel it follows:
| Source | What it offers |
|---|---|
| Default | The normal, recommended channel: the current supported releases of Joomla |
| Next | The next major version, when one is available, for early adopters |
| Custom | A URL you provide yourself, for a private or test update server |
For almost every site, leave this on Default. The component points at Joomla's official update repository at https://update.joomla.org/cms/, which in Joomla 6 is served through a TUF-based (The Update Framework) repository for stronger supply-chain security.
5.2 Minimum Stability
The Minimum Stability option sets the lowest release quality the component will show you. From loosest to strictest:
Development < Alpha < Beta < Release Candidate < StableKeep production sites on Stable so you only ever see finished releases. Lower it only on a test site where you deliberately want to try a beta or release candidate. If an expected update "does not appear", this setting is a common cause: a pre-release is hidden because the setting is Stable, which is exactly what it should do on a live site.
Back to top6. Updating by Uploading a Package
6.1 When You Need It
Some servers cannot reach the update server, or block large downloads, so the live update never finishes. For those cases the Upload & Update tab lets you do the download yourself: get the package from the official Joomla download page, then upload the .zip to Joomla.
6.2 The Captive Login
Uploading and applying a Joomla package is the most dangerous action in the backend, so the component adds an extra gate. After you upload the file, Joomla sends you to a captive login: a locked screen that asks you to re-enter your Super User password (and your Multi-factor Authentication code, if you use it) before it will apply the package.
Upload .zip
↓
Captive screen → re-authenticate as a Super User (+ MFA)
↓
Confirm → apply the package through the same install pipelineThis stops an attacker who hijacked a session, or a forged request, from pushing a malicious package onto your site without a fresh login. The screen is "captive" because you cannot do anything else until you authenticate or cancel.
6.3 The Upload Size Limit
The full Joomla package is several megabytes, so the upload can hit PHP's upload_max_filesize or post_max_size limit and fail silently. If the upload stalls, raise those PHP limits, or use the live update instead. The Pre-Update Check tab reports these PHP values so you can see them at a glance.
7. Automated Updates (New in Joomla 6)
7.1 What It Does
Joomla 6 introduces automated updates: the site can update its own core, on its own, without anyone logging in. This is built for the many sites that fall behind simply because no one runs the update in time. You turn it on once, and Joomla keeps the core current for you.
Automated updates only work on the safe, default setup. The option appears only when Update Source is Default and Minimum Stability is Stable. You cannot auto-apply a beta or a custom channel; that is on purpose.
7.2 How It Works
The clever part is that your site does not run a local scheduler. Instead it registers with an external Joomla service that watches for new releases and triggers the update through the Web Services API:
1. You enable Automated Updates in the Options
2. Joomla generates a secret 40-character update token
3. It registers your site URL + token with autoupdate.joomla.org
4. When a new version ships, that service calls your site's REST API
5. Your site downloads, verifies, and applies the update by itself
6. Joomla emails the result to the people you choseThe token is the shared secret that proves the incoming request is the real service and not an attacker. It is stored in the component parameters and shown (read-only) in the Options once registration succeeds.
7.3 The Health Check
Once registered, the backend shows a small health status indicator (through a quick-icon plugin) that confirms the automated-update connection is alive and was checked recently. If your site has not been reachable for several days, the indicator warns you, because a registered site that the service cannot reach will silently stop updating.
7.4 Email Notifications
An update that happens with no one watching needs to tell someone afterwards. The Send Email to User Groups option chooses which user groups receive a message after an automated update runs. If you leave it empty, Joomla falls back to all Super Users. The email reports the old and new version and the result, so you always know your site changed even though you were not there.
Back to top8. Under the Hood (Developer View)
8.1 The Tables It Touches
com_joomlaupdate has no tables of its own. It reuses the same update plumbing as the extension installer:
| Table | Holds |
|---|---|
#__update_sites |
The Joomla core update URL the component polls |
#__update_sites_extensions |
Links the core update site to the Joomla "file" extension |
#__updates |
The pending core update found during the last check |
#__extensions |
The component's own row, whose params store every option (including the autoupdate token) |
#__schemas |
The applied database-schema version, updated during finalise |
8.2 The Update Pipeline
A core update is, at heart, an "upgrade" install of one giant package over the running site. The component drives it through four controller tasks. The interesting one is finalise, which runs the actual migration:
finaliseUpgrade()
├─ read the core manifest (JPATH_MANIFESTS/files/joomla.xml)
├─ load JoomlaInstallerScript (com_admin/script.php)
├─ run preflight('update') → may abort
├─ copy the new files over the old ones
├─ run the schema SQL → update #__schemas
└─ run postflight('update') → clean up old files, finishThe heavy lifting lives in one class, com_admin's JoomlaInstallerScript. That script is where every version-to-version migration is written: files to delete, settings to change, data to fix. When you read "what changed in this release" at the code level, that script is the place to look.
8.3 The Restoration Engine
The component cannot overwrite its own running files mid-request without risk, so the extraction step uses a small, self-contained helper. Two stand-alone files, extract.php and finalisation.php, run the unzip and restart outside the normal Joomla bootstrap. The component writes a short update file describing the package, then hands control to this engine to extract it. This is why the update survives even while it is replacing core libraries.
8.4 Installer Events
Because an update is an install, the standard installer events fire, and an installer plugin can listen. Joomla 6 adds a dedicated event for the automated path:
| Event | Fires |
|---|---|
onInstallerBeforePackageDownload |
Before the core package is downloaded |
onBeforeJoomlaAutoupdate |
Before an automated update applies; a plugin can stop it |
A plugin that returns a "stopped" result from onBeforeJoomlaAutoupdate can veto an automated update, for example to hold updates during a busy sales period.
8.5 Forcing a Fresh Check in Code
The component caches its update check just like the extension updater. To force a fresh poll from your own code, refresh the updates for the Joomla "file" extension:
use Joomla\CMS\Updater\Updater;
use Joomla\CMS\Extension\ExtensionHelper;
$updater = Updater::getInstance();
$joomlaExtId = ExtensionHelper::getExtensionRecord('joomla', 'file')->extension_id;
// 0 cache timeout = ignore the cache and check now
$updater->findUpdates($joomlaExtId, 0, Updater::STABILITY_STABLE);9. Web Services API and CLI
9.1 The Update Endpoints
Joomla 6 exposes com_joomlaupdate over the Web Services API. These are the routes the automated-update service calls, but you can also use them to script your own update tooling. They live under /api/index.php/v1/joomlaupdate:
| Method & Route | Purpose |
|---|---|
GET .../healthcheck |
Report whether the site is reachable and ready |
GET .../getUpdate |
Return the available update information |
POST .../prepareUpdate |
Download and verify the package, get it ready |
POST .../finalizeUpdate |
Apply the prepared package |
POST .../notificationSuccess |
Record and notify a successful update |
POST .../notificationFailed |
Record and notify a failed update |
9.2 Calling It
With the API enabled and a token created under your user profile, a call looks like every other Joomla Web Service:
curl -H "X-Joomla-Token: <token>" \
"https://example.test/api/index.php/v1/joomlaupdate/getUpdate"These endpoints require the same Super User permission as the screens, so do not expose the token. The split into prepare and finalize mirrors the backend pipeline: first stage the package, then commit it, so a failure during download never leaves a half-applied core.
9.3 The Command Line
For automation, CI/CD, or a server with strict execution-time limits, Joomla ships console commands that drive the same update logic without a browser. Run them through the Joomla CLI entry point, php cli/joomla.php:
| Command | What it does |
|---|---|
core:update:check |
Check whether a new Joomla version is available |
core:update |
Download and apply the available core update |
core:update:channel |
Read or change the update channel (source) |
core:autoupdate:register |
Register the site for the automated update service |
core:autoupdate:unregister |
Unregister the site from the automated update service |
# Check, then update, from the site root:
php cli/joomla.php core:update:check
php cli/joomla.php core:updateRunning the update from the command line avoids the web server's timeout entirely, which is the cleanest fix for a large update that keeps stopping half-way in the browser.
Back to top10. Options and Configuration
10.1 Where the Options Live
Click Options on the Joomla Update screen to reach the component settings. They are stored as JSON in the component's #__extensions row, like every other extension's Options.
| Option | Default | What it does |
|---|---|---|
Update Source (updatesource) |
Default | Which channel to follow: Default, Next, or Custom |
Custom URL (customurl) |
empty | The update URL when the source is Custom |
Minimum Stability (minimum_stability) |
Stable | Lowest release quality the component will show |
Update Notification (versioncheck) |
Show | Whether to show the "new version" notice in the backend |
Backup Reminder (backupcheck) |
Show | Whether to show the "have you backed up?" reminder |
Automated Updates (autoupdate) |
No | Turn on hands-off core updates (Default + Stable only) |
| Send Email to User Groups | Super Users | Who gets the result email after an automated update |
10.2 The Hidden Autoupdate Fields
When you enable automated updates, the component also stores read-only state: the secret update_token, the update_last_check timestamp, and an internal autoupdate_status that records whether the site is registered with the service. You do not edit these; the component manages them as you subscribe and unsubscribe.
11. SEO and Metadata
com_joomlaupdate is an administrator-only component. It has no front-end view, no menu item type, and produces no public pages, so it has no direct SEO footprint. Search engines never see it, and it needs no metadata or sitemap entries.
Its effect on SEO is indirect but large. An out-of-date Joomla is slower, less secure, and more likely to be defaced or injected with spam links, all of which damage rankings. Search engines and browsers also flag compromised sites. Running com_joomlaupdate on time is, in practice, basic SEO hygiene: a current, secure, fast site is the foundation everything else is built on.
Back to top12. Common Mistakes and Pitfalls
12.1 Confusing Core Updates with Extension Updates
Symptom: You update Joomla faithfully, but your add-ons stay outdated (or the reverse).
Fix: These are two components. The CMS updates under System → Update → Joomla (com_joomlaupdate); extensions update under System → Update → Extensions (com_installer). Check both.
12.2 Updating Without a Backup
Symptom: An update breaks the site and you have no way back.
Fix: Always make a full backup (files and database) before you click Install. The backup reminder only asks; it does not create one. Test the backup can be restored.
12.3 Ignoring the Pre-Update Check
Symptom: After a major upgrade, a key extension or your template stops working.
Fix: Run the Pre-Update Check first and update every incompatible extension before the core, especially across a major version jump.
12.4 The Update Will Not Download
Symptom: The live update hangs or times out.
Fix: Your server may not reach the update server, or a proxy blocks it. Use the Upload & Update tab with a package you downloaded by hand.
12.5 An Expected Update Does Not Appear
Symptom: A new version is out, but Joomla does not offer it.
Fix: The check is cached, so click to re-check. Then confirm Minimum Stability is not hiding a pre-release, and that the Update Source is the channel you expect.
12.6 An Update That Stops Half-Way
Symptom: The update errors out partway and the site looks broken.
Fix: Read the Update log to see where it stopped. A timeout often means PHP's max_execution_time is too low for a large package. Raise it, then use Reinstall or re-run the update to finish the file copy and SQL.
12.7 Not Enough Disk Space
Symptom: The download or extraction fails on a large package.
Fix: The update downloads a .zip to the temporary folder and then extracts it, so it briefly needs room for both. Free up disk space (and clear old packages from the tmp folder), then run the update again.
12.8 Automated Updates Silently Stopped
Symptom: You enabled automated updates, but the core is falling behind again.
Fix: Check the health-status indicator. If the service cannot reach your site (a firewall, the API disabled, an expired token), registration goes stale. Re-check the connection and re-enable if needed.
Back to top13. Best Practices
If you only remember a few things from this article, remember these:
- Back up first, every time. The update is one click; recovery without a backup is not.
- Run the Pre-Update Check and clear every red row before you install.
- Update incompatible extensions before a major core upgrade, not after.
- Keep production sites on Default source and Stable minimum stability.
- Test major upgrades on a staging copy before you touch the live site.
- If your server cannot download, use Upload & Update with the official package.
- Consider Automated Updates for sites that keep falling behind, and set the result email so you always know what changed.
- Restrict Super User accounts: only they can run com_joomlaupdate.
14. Quick Reference
OPEN System → Update → Joomla (index.php?option=com_joomlaupdate)
LIVE UPDATE download → install → finalise → cleanup
UPLOAD Upload & Update tab → captive login (+MFA) → confirm
PRE-CHECK PHP version . extensions . database . extension compatibility
REINSTALL overwrite current core files (repair, no version change)
SELF-UPDATE the update component updates itself before a big upgrade
AUTO UPDATE Options → Automated Updates (Default + Stable only)
HEALTH quick-icon shows the autoupdate connection status
SOURCES Default . Next . Custom → update.joomla.org/cms/ (TUF)
STABILITY Development < Alpha < Beta < RC < Stable (default)
REST /api/index.php/v1/joomlaupdate/{getUpdate,prepareUpdate,finalizeUpdate}
CLI php cli/joomla.php core:update . core:update:check . core:autoupdate:register
TABLES #__update_sites . #__updates . #__extensions . #__schemas
ACCESS Super User only (core.admin)15. Summary
com_joomlaupdate is the core component that keeps Joomla itself current. It is not under its own menu; it appears as a single screen under System → Update → Joomla, locked to Super Users.
Once you see how it fits together, the whole job is straightforward:
- Pre-Update Check: tests your server and your extensions before you install, so you fix problems on a working site.
- Live update: one button runs download, install, finalise, and cleanup, with a clear error and a log if anything fails.
- Upload & Update: a manual path guarded by a captive login when the live update cannot run.
- Channels and stability: Default source and Stable stability keep production sites on safe, finished releases.
- Automated Updates: new in Joomla 6, the site registers with an external service and updates its own core, then emails you the result.
If you are planning a Joomla upgrade, worried that a site has drifted out of date, or facing an update that will not finish, it pays to understand how com_joomlaupdate works. It is the component that decides how secure and current your whole site stays, so knowing its screens, its checks, and its new automated path is a core part of keeping any Joomla site safe.
Back to top
