Updating Joomla and Automated Core Updates

This content was generated with the assistance of AI and should be verified against the official Joomla documentation before being relied on in production.

This sub-section’s Joomla bibliography lists the reference material consulted while preparing these pages.

Keeping the core current is the single most effective security measure for a Joomla site, and it is also the task that administrators most often get wrong, because several different mechanisms are involved: the Joomla Update component (com_joomlaupdate), the update server and its signed metadata, the compatibility check of installed extensions, the database schema check and, since Joomla 5.4 and 6.0, a service that updates the site without anyone clicking a button. This page covers all of them in detail, using the fictitious Tallpine Hiking Club site (package pkg_tallpine, component com_tallpine, child template cassiopeia_tallpine) that is built across this sub-section.

It was written against Joomla 6.2.x on PHP 8.3+ and checked on 2026-10-30. Joomla 6.2 is the current release, 5.x is in its security-only period (5.4.10 was the last bugfix release; security fixes continue until 2027-10-12), and 4.x is end of life, so a site still on 4.x should first follow Upgrading Joomla 4 to 5 and Upgrading Joomla 5 to 6. The release cadence and support windows are described in Versions, Release Cycle and Support.

Who does what

Role Responsibility

Administrator (Super User)

Chooses the update channel, runs updates from System → Update → Joomla, receives the notification and the automated-update emails, resolves the pre-update warnings.

Site builder

Keeps third-party extensions, such as pkg_tallpine, compatible with the next minor or major version and publishes update information for them (see Update Servers and the JED).

Operator / DevOps

Runs core:update from a deployment pipeline, decides whether the production site is reachable by the automated update service, takes backups beforehand (see Backups and Recovery).

Developer

Reads the migration notes for the target version before updating and tests the update on staging (see Deprecations and Preparing for Joomla 7).

Terminology: minor, patch and major updates

Joomla follows a semantic-versioning-like scheme, with the caveats described in the Developer Manual: a patch release (6.2.1 to 6.2.2) fixes bugs and security issues, a minor release (6.1 to 6.2) adds features and raises no minimum requirements, and a major release (5.4 to 6.0) is the only point at which requirements rise and deprecated code is removed. Downgrading is not supported, so the only way back after a failed update is a restored backup.

The distinction matters in the Joomla Update screen: the pre-update check is shown for minor and major updates but not for patch releases, and the Automated Core Updates service handles minor, patch and security releases only, never a major upgrade.

The Joomla Update component

Reaching the screen

An administrator reaches the component in two ways. When an update exists, the notification panel on the Home Dashboard shows an "x.y.z Available - Update Now!" button. Alternatively, System → Update → Joomla (the Update panel of the System dashboard) shows the available version and a link to the component. The Quick Icon plugin Quick Icon - Joomla! Update Notification produces the dashboard notice; if it is disabled, the icon stays inactive but can still be selected to open the component.

The component’s code lives in administrator/components/com_joomlaupdate: UpdateModel finds, downloads and finalises updates, extract.php and finalisation.php run the extraction and the last step outside the normal request cycle, and config.xml declares the options described next. The CMS also exposes a Web Services API for the component (api/components/com_joomlaupdate), which is what the automated service uses.

Source: Joomla User Guide: Version Update

Options: channels, stability and checkboxes

Options in the toolbar of System → Update → Joomla opens the configuration of the component. The fields below are taken from the config.xml of Joomla 6.2.

Field (parameter) Meaning Default

Update Channel (updatesource)

default: the official project’s non-testing releases of the current major version. next (shown as Joomla Next): lets the site see the next major version once the latest release of the current one is installed. custom: a URL that you provide in Custom URL (customurl); http, https, ftp and ftps schemes are accepted.

Default

Minimum Stability (minimum_stability)

The least stable update that is offered: Development (0), Alpha (1), Beta (2), Release Candidate (3) or Stable (4). An update that does not state a level is treated as Stable.

Stable

Potentially incompatible extensions checkbox (versioncheck)

Shows a confirmation checkbox in the pre-update check when an installed extension might not be compatible with the target version family (minor or major).

Show

Confirm Backup Checkbox (backupcheck)

Shows the "I have a backup" checkbox on the last step before the update is applied.

Show

Older documentation and older books describe four channels: Default, Joomla Next, Testing and Custom URL. In the 6.2 source the Testing radio button no longer exists. Pre-release builds are selected with Minimum Stability instead, and the legacy values (lts, sts, testing, nochange) are all treated as default, as the comment in applyUpdateSite() documents. A site that must test a release candidate sets the minimum stability to Release Candidate on a staging copy, never on production. Because automated updates are available only with the Default channel and Stable minimum stability, changing either value disables them (the Options screen then shows an information note instead of the automated-update fields).

When the channel is saved, applyUpdateSite() rewrites the update site record of the joomla file extension in the #__update_sites table: the location becomes https://update.joomla.org/cms/ for every channel other than custom, the cached rows in #__updates for the core are deleted, and the next check fetches fresh data. A custom URL ending in .xml is treated as a classic update collection; any other custom URL is treated as a TUF repository.

Source: Joomla User Guide: Joomla 5 to 6 planning and upgrade step by step

What "Joomla Next" does

The Joomla Next channel exists to move between majors. The sequence for the Tallpine site is: update to the latest 5.4.x on the Default channel, disable the old Behaviour - Backward Compatibility plugin, enable Behaviour - Backward Compatibility 6 (the two cannot be enabled together), choose Joomla Next in the Options, save, and press Check for Updates. The 6.x release then appears as an available update. After a successful update the core resets the channel from next back to default by itself (resetUpdateSource()), and logs a warning if it cannot write the parameter. The complete major-upgrade procedure, including the removals in 6.0, is in Upgrading Joomla 5 to 6.

TUF-signed core updates

Since Joomla 5.1 the update metadata for the core is protected by The Update Framework (TUF), a specification for secure software-update systems that defends against an attacker who controls the download server or the network. The core’s update site (https://update.joomla.org/cms/) publishes signed metadata (roles for root, targets, snapshot and timestamp); the site downloads it with a small client in libraries/src/TUF (TufFetcher, HttpLoader, DatabaseStorage) and stores the verified metadata in the #__tuf_metadata table.

TUF changes what an administrator sees when something goes wrong. Joomla maps the library’s exceptions to specific messages:

Condition Message in the administrator

Freeze attack

The update is refused because the offered metadata has expired.

Rollback attack

The update is refused because the offered version is older than the installed one.

Signature threshold not reached

The update is refused because it does not have enough signatures.

Invalid stored metadata

The saved TUF update information is invalid.

Unexpected download size

The size of the downloaded update did not match the expected size.

Anything else

"Could not fetch update information, enable system debug mode for further information."

Three practical consequences follow. First, the server clock matters: metadata carries expiry dates, so a machine whose clock is far wrong can see the "expired" message. Second, a reverse proxy or security product that rewrites the responses of update.joomla.org breaks verification, which is the point of TUF. Third, the Joomla language file notes that TUF is not yet available for extensions, so third-party update servers continue to use the classic XML format and are protected by checksums and HTTPS only; see Update Servers and the JED.

Joomla 5.0 and earlier verified only the SHA checksum published beside the download, which protected against corruption but not against a compromised update server. Older books such as Developing Extensions for Joomla! 5 (2023) and Joomla! 4 Masterclass (2023) predate TUF and describe only the XML update collection.

Source: joomla-cms: libraries/src/TUF

The pre-update check

For minor and major updates (not for patch releases) the component shows a Pre-Update Check before offering the Update button. Its sidebar has three parts:

  • Required Settings: PHP version, database type and version, and PHP extensions such as zlib, xml, json and mbstring. If a required setting fails, the check is not offered because the server cannot run the target version.

  • Recommended Settings: PHP ini values (for example output_buffering). These warnings are often specific to the server and usually do not block the update.

  • Extensions: an overview of non-core extensions in three groups: extensions with an update available, extensions for which the developer publishes no information, and extensions that report that no update is needed.

Behind the third part, UpdateModel::fetchCompatibility() asks each extension’s update site for update entries whose targetplatform matches the target Joomla version. Plugins in the groups that cannot be disabled safely (system, user, authentication, actionlog and multifactorauth) are checked separately. If a request times out or the update server returns something unusable, the extension is listed under Pre-Update Checks Failed rather than as compatible.

Limits of the check

The check is a high-level overview, and the User Guide says so explicitly: the missing green check mark of an extension does not prove it is incompatible, and a green check mark does not prove it works. The Joomla 5 to 6 upgrade guide goes further and calls the check not a reliable source of truth, advising that the administrator verify extensions on the vendors' sites and in System → Manage → Extensions. Typical reasons for a wrong answer:

  • the developer never published targetplatform information for the new version although the extension works;

  • the update XML of an older extension lists a platform regular expression that excludes newer releases (for example 4\.[0-9] written without a wildcard for 5 or 6), so the check reports a problem that does not exist, or the reverse;

  • the extension needs a download key, so the update server answers with an error, which appears as a failed check;

  • the check cannot see template overrides, custom code in cassiopeia_tallpine, or use of removed APIs in the site’s own code, and it never runs the extension.

The reliable approach for pkg_tallpine is to test the update on a staging copy with Debug System enabled and to read the deprecation log, as described in Deprecations and Preparing for Joomla 7.

The Potentially incompatible extensions checkbox option can hide the confirmation tick box, but doing so removes the last warning in front of the administrator and is rarely a good idea.

Source: Joomla User Guide: Joomla 5 to 6 planning and upgrade step by step

Updating from the administrator interface

The manual procedure has been stable for years and is the baseline for everything that follows:

  1. Take a backup of the files and the database, and confirm that it can be restored.

  2. Open System → Update → Joomla. Review the pre-update check and fix the highlighted issues, which may mean updating, disabling or uninstalling extensions.

  3. Select Update. On the confirmation screen tick the checkbox that confirms the backup and the extension compatibility, then select Start Update.

  4. Wait for the progress bar to reach 100%. A system message confirms the new version, which is also shown in the toolbar.

  5. Check the front end (use Shift + Reload to bypass cached stylesheets and scripts) and the System dashboard for items marked with a number.

  6. Go to System → Maintenance → Database and run Update Structure if it reports problems (next section).

  7. Go to System → Discover and install any new core extensions the update added; repeat until nothing is listed.

If the server is behind a firewall or cannot reach the update servers, a link below the Update button allows the update package (Joomla_x.y.z-Stable-Update_Package.zip) to be uploaded manually. The update writes a log to administrator/logs/joomla_update.php, which records the download, the extraction, the SQL updates and the cleanup; this is the first file to read when an update stalls.

How the update runs internally: UpdateModel::download() fetches the package and verifies its checksum, then createRestorationFile()/createUpdateFile() write a one-time file and password so that the extraction script extract.php can run without bootstrapping the CMS. After extraction finalisation.php calls finaliseUpgrade(), which executes the SQL update scripts and the script.php of the files_joomla package. cleanUp() removes the temporary files and writes the action log entry. Because the CMS files are being replaced while the request is running, the session is carried by the "captive" login, which asks for credentials again if the session is lost during the update.

Source: Joomla User Guide: Version Update

Update Structure in the Database screen

Core updates change the database schema through versioned SQL files in administrator/components/com_admin/sql/updates. finaliseUpgrade() runs them, but they can be skipped by an error. System → Maintenance → Database compares the schema version recorded in #__schemas with the SQL files and the actual tables. It reports "Database table structure not up to date" with the failing statements. Select the extension named Joomla (or the affected extension), tick the rows, and press Update Structure in the toolbar. The same operation is available on the command line as maintenance:database --fix.

Common causes of a failing structure update are a database user without ALTER privileges, a partly applied previous update, tables in a different storage engine or collation, and third-party extensions whose SQL has errors. The CLI core:update refuses to start if the schema check reports errors, which makes this screen the prerequisite for automation as well. The MySQL and PostgreSQL schema files are separate; Joomla does not translate SQL between them, and migrating a site from MySQL to PostgreSQL is not supported. Installer scripts and SQL for the Tallpine component follow the same mechanism, covered in Installer Scripts and SQL Updates.

Source: Joomla User Guide: Version Update

Removing old files after an update

An update copies the new files over the old ones and does not remove files that the new release no longer ships. The script.php of com_admin contains deleteUnexistingFiles(), which has a hard-coded list of files and folders that were removed from the core since earlier versions and deletes them during finaliseUpgrade(). Leaving obsolete files in place is a security risk (an old, vulnerable script can remain reachable) as well as a source of confusion.

The method takes a dry-run argument and returns an array with files_exist, folders_exist, files_deleted, folders_deleted, files_errors and folders_errors. Errors appear when the web server user cannot delete a file, typically because files were uploaded by a different user. Other consequences:

  • a deleted file that a template override or custom code still includes will break the page, which is one more reason to test on staging;

  • files that Joomla does not list, such as leftovers from third-party extensions or from a manual copy of the previous version, stay in place, and a periodic review of the document root is part of hardening (see Security Hardening, MFA and Passkeys);

  • the same list is used when updating a site from 5.x to 6.x, so the first 6.x cleanup removes the 5.x leftovers.

The same routine can be run on its own at any time with the console command update:joomla:remove-old-files, which has a --dry-run option that lists what would be removed without deleting anything. On a site updated through the web interface or by replacing files by hand, a dry run followed by the real run is the quickest way to verify that no leftovers remain.

php cli/joomla.php update:joomla:remove-old-files --dry-run
php cli/joomla.php update:joomla:remove-old-files

Source: joomla-cms: RemoveOldFilesCommand.php

Source: joomla-cms: administrator/components/com_admin/script.php

Update notifications

Independently of Automated Core Updates, Joomla can mail the Super Users when it finds updates for the core or for extensions. The Task - Joomla! Update Notification plugin runs as a scheduled task (System → Scheduled Tasks → Update Notification) with a Frequency in hours (default 24; 0 sends mail on every visit and is intended only for testing), an optional comma-separated list of Super User Emails, and an Email Language. The mail is built from the mail template Joomla: Update Notification in System → Email Templates. Scheduled tasks run on page visits unless a real cron job calls the CLI, so a very quiet site can notify late; see Scheduled Tasks and Mail Templates and Email Settings.

Source: Joomla User Guide: Joomla! Update Notification plugins

Automated Core Updates

What it is and what it updates

Automated Core Updates were introduced in Joomla 5.4 and 6.0 (October 2025). The core keeps itself current for minor, patch and security releases: for the Tallpine site on 6.2.0, the service would apply 6.2.1, 6.2.2 and so on, and later 6.3.0, but never 7.0. A major upgrade is always a deliberate action taken by an administrator after the steps in the upgrade guide. Extensions, templates and languages are not part of it; they continue to use the normal update mechanism and the notification described above.

The design is notable because the update is not pushed from outside as a file transfer. The project runs an update service (the code names https://autoupdate.joomla.org/api/v1), and the site registers with it; when a new release exists, the service calls the Web Services API of the registered site, and the site downloads, verifies and installs the release itself from the official update server.

Defaults

  • New installations: Automated Updates are on by default. The installer shows an Automated Updates step that explains the service and offers a Disable Automated Updates button, so it is an opt-out.

  • Upgraded sites: the feature is off. After updating a site to 5.4 or 6.0 the post-installation messages show Automated Joomla Updates with an Activate Automated Updates button; the administrator opts in. A quick icon from the Quick Icon - Joomla! Automated Update Status Notification plugin reports the registration state on the Home Dashboard.

  • Registering the site discloses to the Joomla project the site URL, the PHP version, the database type and version, the CMS version and the server operating system, as the Options screen and the installer say; the project states that the information is used only to improve the service. This is the data protection point to decide on before enabling the feature, and it belongs in the privacy review described in Privacy and Action Logs.

Requirements

  • Joomla 5.4 or later (or 6.0 or later).

  • The site must be publicly reachable from the internet. If the registration request finds that the site cannot be reached, the service answers with a validation error (HTTP 422); Joomla then shows "The automated update service is unavailable for your site as it’s not accessible from the internet" and disables the option. A local Docker Compose site, a staging site behind a VPN or a site behind HTTP basic authentication cannot use the service, which is why the Tallpine development stack ( Local Development with Docker) and the staging site update with core:update instead.

  • Update Channel must be Default and Minimum Stability must be Stable. Anything else makes the API return "Auto update is disabled" (404) and hides the automated-update fields.

  • The server must satisfy the target release’s requirements: the health check reports update_requirement_state, and the update offer is suppressed when any PHP option required by the target version fails.

  • Super Users or the selected groups should have Receive System Emails enabled, otherwise they receive no result mail.

Settings

In the Automated Updates tab of the component Options:

Field Purpose

Automated Update (autoupdate)

Switch on or off. Saving with the switch on registers the site; saving with it off unregisters it.

Update token (update_token)

A read-only 40-character random token generated on first registration. The site compares it with the X-Jupdate-Token request header on every call and rejects other values. It is stored in the parameters of the com_joomlaupdate row of #__extensions, so it is part of every database backup and must be handled like a secret.

Last check (update_last_check)

The last time the service reached the site (set by a successful health check). If it is old, the page advises re-saving the configuration to start the registration again.

Send Email to User Groups (automated_updates_email_groups)

User groups that receive the result mail. If no user is found, all Super Users receive it.

The hidden autoupdate_status value records the registration state (unsubscribed, subscribed). The enumerations AutoupdateState, AutoupdateRegisterState and AutoupdateRegisterResultState in the component describe the states.

How joomla.org triggers the site

The service uses six public routes registered by the Web Services - Joomla Update plugin (plg_webservices_joomlaupdate). Each route is public in the Web Services sense (no API user is needed), and each validates the update token itself. They live under the site’s api entry point:

Method and path Controller action Purpose

GET /api/index.php/v1/joomlaupdate/healthcheck

healthcheck.show

Returns php_version, db_type, db_version, cms_version, server_os and update_requirement_state, and records the time of the last check.

GET /api/index.php/v1/joomlaupdate/getUpdate

updates.getUpdate

Returns availableUpdate: the latest version, or null when the site is current or the requirements are not met.

POST /api/index.php/v1/joomlaupdate/prepareUpdate

updates.prepareUpdate

Body targetVersion. Downloads the package, checks the version and the checksum, creates the extraction file and returns password, filesize and filename. Responds 410 if the target version is no longer the latest.

POST /api/index.php/v1/joomlaupdate/finalizeUpdate

updates.finalizeUpdate

Body fromVersion and updateFileName. Runs the finalisation, the cleanup and the reset of the update source, and returns success and any errors.

POST /api/index.php/v1/joomlaupdate/notificationSuccess

notification.success

Body fromVersion and toVersion. The site sends the "Automated Joomla Update Succeeded" email.

POST /api/index.php/v1/joomlaupdate/notificationFailed

notification.failed

The same for the "Automated Joomla Update Failed" email.

Between prepareUpdate and finalizeUpdate the extraction of the downloaded package takes place; prepareUpdate returns the password and file name that the extraction script (extract.php, the same mechanism as in a manual update) needs, so the heavy file replacement is not done inside an API request. Before extraction starts the core dispatches the event onBeforeJoomlaAutoupdate to plugins of the installer group; a plugin that calls stopUpdate() on the BeforeJoomlaAutoupdateEvent aborts the run with HTTP 503. That hook is the supported place for a site to veto an update, for example while a trail-closure import is running.

The sequence below shows an automated update of the Tallpine site from 6.2.1 to 6.2.2.

sequenceDiagram autonumber participant J as Joomla autoupdate service participant U as update.joomla.org (TUF repository) participant S as Tallpine site (api and administrator) participant D as Site database participant A as Administrators J->>S: GET healthcheck with X-Jupdate-Token S->>D: store update_last_check S-->>J: PHP, database, CMS version, OS, update_requirement_state J->>S: GET getUpdate S->>U: refresh update information and verify TUF metadata U-->>S: signed metadata, release 6.2.2 S-->>J: availableUpdate 6.2.2 J->>S: POST prepareUpdate with targetVersion 6.2.2 S->>U: download package and verify checksum S->>S: dispatch onBeforeJoomlaAutoupdate to installer plugins S-->>J: password, filesize, filename J->>S: run the extraction step with the password S->>S: replace core files J->>S: POST finalizeUpdate with fromVersion and updateFileName S->>D: run SQL updates, update schema version S->>S: delete obsolete files, clean up, reset update source S-->>J: success true, errors empty J->>S: POST notificationSuccess S-->>A: email Automated Joomla Update Succeeded

If any step fails the service posts notificationFailed, and the site mails the same recipients with a message that points to administrator/logs/joomla_update.php. The mail text states that it is sent by the site and not by the Joomla project, which is a phishing reminder: the project never contacts site owners about a failed update.

Source: joomla-cms: api/components/com_joomlaupdate

Notification emails

Two mail templates (System → Email Templates, component Joomla Update) are sent: Automated Joomla Update Succeeded and Automated Joomla Update Failed. They carry the site name, URL, old and new version, and, for failures, the location of the log. They obey the normal mail-template rules (languages, HTML or plain text, logging), so the mail configuration in Global Configuration → Server → Mail must work, or no result will reach anyone. Recipients are the user groups chosen in the Options and must have Receive System Emails turned on in their profile.

Operating notes and pitfalls

  • Firewalls and reverse proxies: the service needs unauthenticated access to /api/index.php/v1/joomlaupdate/*. Rules that block /api, require basic authentication in front of it, or strip the X-Jupdate-Token header cause the registration to fail or the last-check date to stay old. Never allow the whole API to the world just for this; restrict the rules to the six paths above where the proxy allows it. Configuration details are in Web Server, Reverse Proxy and HTTPS.

  • Multiple application servers: the update replaces files on one node. With several web servers or containers (see Kubernetes deployment strategies) a self-update on one replica leaves the others on the old code and the image, which is rebuilt from the old sources, undoes the update on the next deployment. In immutable-container deployments disable automated updates and update by building a new image with the new Joomla version, as described in Multi-Site Options and Scaling.

  • Read-only file systems and file ownership that prevents PHP from writing the core directories make the update fail at extraction; the failure mail is then the only sign.

  • Third-party extensions are not checked by the service. A new core minor can break an extension such as com_tallpine that uses an API changed or removed in that minor. This is the main argument for keeping extensions current, for a staging site and for keeping automated updates to the patch level on sites with custom code.

  • Backups: nothing in core takes a backup before an automated update. A scheduled backup (Akeeba Backup and similar tools are third-party) or a database snapshot is the operator’s responsibility; see Backups and Recovery.

  • Opting out later: switching the option off, or running the unregister command below, stops the calls. Sites that should never auto-update (regulated environments) keep it off and rely on notification mails.

  • Failures are silent without mail: if mail is not configured, check joomla_update.php and the Last check date.

Source: joomla-cms: UpdateModel.php (changeAutoUpdateRegistration)

Registering from the command line

The registration is also available as console commands, which fit provisioning scripts:

# register a publicly reachable site; --live-site must contain scheme and host
php cli/joomla.php core:autoupdate:register --live-site=https://www.tallpine.example

# stop receiving automated updates
php cli/joomla.php core:autoupdate:unregister --live-site=https://www.tallpine.example

Source: joomla-cms: AutomatedUpdatesRegisterCommand.php

The register command stops with an error when --live-site is missing or lacks a scheme or host, and exits with a failure code when the service does not accept the registration.

Updating from the command line

The CLI is the right tool for staging, for containers and for deployment pipelines. Joomla 6.2 ships these core commands (the core: namespace belongs to the console application of the CMS; see Command Line Interface):

Command Behaviour

core:update:check (alias core:check-updates)

Purges the cached update information, fetches fresh data, prints the channel in use, the current version and whether a newer version exists. It changes nothing and exits successfully in both cases.

core:update:channel [channel] [--url=...]

Without an argument it prints the current channel. With default, next or custom it stores the value in the component parameters and applies the update site; custom requires --url.

maintenance:database --fix

Applies the database structure update, like Update Structure.

update:joomla:remove-old-files [--dry-run]

Deletes (or with the option lists) the obsolete core files.

core:update

Runs the whole update: checks that an update exists, checks the database structure, for a major version checks the backward-compatibility plugins, downloads and extracts the package, copies the files, finalises, resets the channel from next to default, removes administrator/cache/autoload_psr4.php and joomla.xml, and cleans up.

core:update exit codes are 0 for success, 1 when a precondition failed (no update, schema errors, or the BC plugin state is wrong for a major upgrade) and 2 when the update itself failed, so a pipeline can distinguish them. The command tests the Joomla update log before starting and aborts if it cannot write it. It does not take a backup, does not ask for confirmation and does not run the pre-update extension check; those are the operator’s job.

For a major upgrade the command checks that the plugin Behaviour - Backward Compatibility of the current major is disabled and that the plugin for the next one is enabled, and prints an error for each violation. The new files are copied without the web interface’s captive-login mechanism, so the command is suitable for a container image build:

#!/usr/bin/env bash
# update-tallpine-staging.sh: run on the staging host inside the project directory
set -euo pipefail

docker compose exec -T joomla php cli/joomla.php core:update:channel default
docker compose exec -T joomla php cli/joomla.php core:update:check
# take a database dump with the tool of your choice before this point (see the backups page)
docker compose exec -T joomla php cli/joomla.php core:update
docker compose exec -T joomla php cli/joomla.php maintenance:database --fix
docker compose exec -T joomla php cli/joomla.php update:joomla:remove-old-files
docker compose exec -T joomla php cli/joomla.php cache:clean

Source: Joomla User Guide: Using the CLI

maintenance:database --fix is the CLI counterpart of Update Structure, and update:joomla:remove-old-files repeats the cleanup of obsolete files. Verify the command names with php cli/joomla.php list on the installed version. The Docker Compose setup used for the Tallpine stack is described in Local Development with Docker and, for the generic Compose concepts, in Compose for local development. In Kubernetes the same commands run as a one-off Job before the new Deployment starts; see Jobs and CronJobs.

Because the container image is the unit of deployment, many teams update the core by changing the image tag and running the schema update, not with core:update:

services:
  joomla:
    # pin the exact patch release; change the tag to update the core
    image: joomla:6.2.0-php8.3-apache
    environment:
      JOOMLA_DB_HOST: db
      JOOMLA_DB_USER: tallpine
      JOOMLA_DB_PASSWORD: ${TALLPINE_DB_PASSWORD:?set in .env, not committed}
      JOOMLA_DB_NAME: tallpine
    volumes:
      - tallpine_media:/var/www/html/images
  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: tallpine
      MARIADB_USER: tallpine
      MARIADB_PASSWORD: ${TALLPINE_DB_PASSWORD:?set in .env, not committed}
      MARIADB_RANDOM_ROOT_PASSWORD: "1"
volumes:
  tallpine_media:

Source: Docker Hub: joomla official image

With an image-based flow the automated service is disabled, and System → Maintenance → Database (or the CLI equivalent) runs the schema update after the new container starts.

A safe update routine for the Tallpine site

  1. Read the release announcement and, for a minor or major release, the migration notes of the Developer Manual (https://manual.joomla.org/migrations/ and https://manual.joomla.org/updates/).

  2. Update extensions first on staging, then the core, then the child template and pkg_tallpine, and review the pre-update check.

  3. Take a backup and verify that it restores.

  4. Run the update (button, core:update or new image) on staging; check System → Maintenance → Database, System → Discover, and the front end and back end with debug on.

  5. Repeat on production in a maintenance window, or let the Automated Core Updates handle patch releases once staging has proved the minor.

  6. Confirm the version in System → System Information and keep the update log.

Common errors

Symptom Likely cause and remedy

No update shown although a release exists

The update cache (#__updates) is stale, the channel is wrong, or the minimum stability is too high. Use Check for Updates, core:update:check, or purge the cache.

"Could not fetch update information"

TUF verification or the network failed. Enable Debug System for the underlying message; check the server clock, DNS and outgoing HTTPS to update.joomla.org.

Update stops at a percentage

PHP time or memory limit, a full disk, or a permission problem. Read administrator/logs/joomla_update.php.

Locked out after the update

Session lost during the file replacement; log in again through the captive login. A white page usually indicates an incompatible extension; disable it through the database.

Database structure errors afterwards

Run Update Structure; for an extension, update the extension first.

Automated updates switch themselves off

The site is not publicly reachable (HTTP 422 at registration), or the channel or stability was changed.

"Auto update is disabled" (404) from the API

The channel is not Default, the stability is not Stable, or the option is off.

Wrong or missing token (403)

The X-Jupdate-Token header was removed by a proxy, or the site was cloned from another with the old parameters; re-save the Options to register again.

A site copied from production to staging also copies the registration. A staging clone that keeps autoupdate on and a reachable URL can register a duplicate, so disable the option in the copy and consider changing the update token.

Security notes

  • Updating promptly is a security measure: security fixes are published by the Joomla project in patch and minor releases. The Security Centre on developer.joomla.org lists advisories; see Security Hardening, MFA and Passkeys.

  • Since 6.2, extension updates carry a security-severity flag, so an administrator can tell a security update of an extension from a feature update; the core’s own update information has always distinguished security releases.

  • Treat the update token as a credential. Do not log it, do not copy it into tickets, and re-register after restoring a database backup on another host.

  • The update.joomla.org TUF protection covers the core only; extensions use their own update servers.

  • The Automated Core Updates feature increases the attack surface by exposing six public API routes; each is protected by the token and by the enabled state, but the exposure should be reviewed against the policy of the organisation.

Corrections to older material

  • Developing Extensions for Joomla! 5 (2023) shows update XML examples whose targetplatform stops at Joomla 5.0 and database minimums of the Joomla 4 era. Use the platform expression for the version family you support and the 6.x requirements: the Developer Manual lists MariaDB 10.4 and PostgreSQL 12 as the enforced minimums and 10.6 and 14 as supported, while the Joomla 5 to 6 upgrade guide gives 10.6 and 14 only, so plan for the higher values.

  • Joomla! 4 Masterclass (2023) describes Joomla 4 as the target, the older four-channel Options screen with Testing, and no TUF or automated updates; Joomla 4 reached end of life in October 2025.

  • Wiki pages on docs.joomla.org describing "Joomla Update" mark themselves as obsolete; the User Guide and the Developer Manual are the current sources.

References