Joomla Extensions: Installing, Updating and Update Sites

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.

This page explains how code gets into a Joomla site and how it is kept current: the five ways of installing an extension, the Extensions Manager screens, update sites and download keys, the security flag that extension updates can carry since Joomla 6.2, what disabling and uninstalling really do, and how to judge a third-party extension before trusting it. It was checked on 2026-10-30 against Joomla 6.2.x and PHP 8.3 or later.

It is written for the site administrator who installs and updates extensions, and for the developer who publishes them. The running example is the Tallpine Hiking Club site: the club installs a third-party gallery component and a commercial backup extension, and publishes its own package pkg_tallpine (component com_tallpine, module mod_tallpine_nexthikes) from its own update server. How such a package is built is covered in Extension types, manifests and packaging; how update servers are written is covered in Update servers and the JED; updating Joomla itself is covered in Updating Joomla and automated core updates.

The Extensions Manager at a glance

Everything on this page happens in the Extensions component, com_installer, reached from the administrator menu under System. Its screens are:

Screen Purpose Typical user

System → Install → Extensions

Tabs for every install method: Upload Package File, Install from Folder, Install from URL, Install from Web (JED) and Discover.

Administrator

System → Manage → Extensions

Lists installed extensions with type, client, folder, version and status; enable, disable, uninstall and refresh the manifest cache.

Administrator

System → Manage → Update Sites

Lists the update servers registered by installed extensions; enable, disable, delete, rebuild, store download keys.

Administrator, developer

System → Update → Extensions

Checks the update sites for newer versions and installs them; shows the security flag since 6.2.

Administrator

System → Information, Database, Warnings, Languages

Related tabs of the same component: database schema checks, installer warnings, language packs.

Administrator

The Joomla User Guide covers installing an extension, the Joomla Extensions Directory and the Vulnerable Extensions List; the Manage, Update Sites and Update screens are described below from the behaviour of com_installer and the Joomla Manual. Access to every screen is controlled by the ACL of com_installer (see Users, groups, access levels and ACL): installing needs core.manage and core.create, changing state needs core.edit.state, uninstalling needs core.delete, and rebuilding update sites needs core.admin. Installing code is the most privileged thing an administrator can do, because an extension runs PHP with the full rights of the web server user. Treat the Super User and any group with core.create on com_installer accordingly.

Installing an extension

An extension in the broad sense is a component, module, plugin, template, language, library, file or package (see Extension types, manifests and packaging). All installer methods end in the same code: Joomla obtains a package, unpacks it in the temporary folder, finds the XML manifest whose root extension element carries a type attribute, selects the installer adapter for that type and runs it. Only the way the package arrives differs.

flowchart TD A[Package source] --> U[Upload Package File] A --> F[Install from Folder] A --> R[Install from URL] A --> W[Install from Web - JED] A --> D[Discover - files already on disk] U --> T[Unpack into tmp folder] F --> T R --> T W --> R T --> M{Manifest found?} M -- no --> X[Error: unable to find install package] M -- yes --> AD[Pick installer adapter by type] AD --> S[Run install script and SQL] D --> E[Register row with state -1] E --> AD S --> OK[Row in extensions table, enabled flag set]

Upload Package File

This is the default route. On the Upload Package File tab, drag the .zip (or .tar.gz) into the drop area or browse for it, and installation starts at once. After a successful install, modules and plugins usually still have to be enabled, and the extension’s own documentation may describe extra steps.

The usual failure is size. The upload is bound by the PHP settings upload_max_filesize, post_max_size and max_execution_time, and by any limit set in the web server or reverse proxy. A package that is too large produces an empty request and a generic error rather than a helpful message. The folder or URL methods avoid the limit. Joomla also needs a writable temporary folder (the Temporary Folder of Global configuration); an unwritable tmp is the second most common cause of "unable to upload" errors.

Install from Folder

For packages too large to upload, unzip the archive on your machine, copy the contents with SFTP into a folder below the tmp directory of the site (for example tmp/gallery-3.2), type that server path into Install Directory and choose Check and Install. The manifest must sit in the folder root. Remove the folder afterwards, because the install leaves the source files behind and tmp is not a place to keep code.

Install from URL

Paste the HTTPS address of the package and Joomla downloads it on the server with its HTTP client, then continues as for an upload. This skips two transfers through your own connection. Internally the helper InstallerHelper::downloadPackage() sets a user agent, lets installer plugins adjust the URL and headers (this is how some vendors add a download key), follows redirects and saves the file in the temporary folder. Requirements are outbound HTTPS from the server and a writable tmp; on locked-down hosts and in containers with egress rules, this method is the first to fail. Use only vendor URLs you have checked, since the server fetches whatever address it is given.

Install from Web (JED)

The Install from Web tab lists extensions of the Joomla Extensions Directory (JED), sorted by number of reviews by default and filterable by category, and installs one with a click. It is slow because it queries the JED live, and it can appear first in the tab order. The order of the tabs is controlled by the Installer plugins: in System → Manage → Plugins, filter the group Installer and reorder or disable the entries. A hardened production site often disables the web installer entirely so that nobody installs code straight from a catalogue. The JED itself is a directory of free and commercial extensions with reviews; for a production decision, open the extension’s JED listing and the vendor site instead of relying on the in-admin list.

Discover

Discover registers an extension whose files were copied to the server by hand, which helps on low-cost hosting where neither upload nor URL works. Place the files first:

Location Content

components/com_<name>

Site files of a component

administrator/components/com_<name>

Administrator files

media/com_<name>

CSS, JavaScript and images

language/en-GB and administrator/language/en-GB

Language files, if not already inside the component folder

Then open the Discover tab and choose Discover. Joomla scans the manifests it finds, lists the extensions that are not yet registered, and on Install creates the rows in the extensions table. Discovered rows carry state -1 until installed. The User Guide itself warns that the method may not fully work: install scripts, SQL files and the update-site registration that a normal install performs may be skipped, so prefer the other methods whenever they are possible.

Source: Joomla User Guide: Installing an extension

Packages, types and what the installer checks

The root extension element of the manifest decides the adapter, and a type="package" manifest lists child extensions that are installed in turn, which is how pkg_tallpine installs com_tallpine, mod_tallpine_nexthikes and the plugins in one step. If any child fails, the package install is rolled back as far as the adapters support. Common errors:

  • Unable to find install package: the zip contains a folder wrapping another zip (typically a download from a marketplace that bundles documentation); unzip once and upload the inner package.

  • Extension is already installed: installing over an existing version is treated as an update; for a different type with the same element the install is refused.

  • Joomla minimum version or PHP errors: the manifest targetplatform and php_minimum are checked against the running site.

  • A "malformed" update message later on comes from a download URL that contains a line break in the update XML, not from the package.

The installer also runs the package’s install script and the SQL files named in the manifest; these are the subject of Installer scripts and SQL updates.

Update sites

Every extension that wants to be updated declares at least one update server in its manifest; the installer copies that declaration into the tables #__update_sites (the server) and #__update_sites_extensions (which extension it belongs to). The check for updates then downloads the XML from each enabled update site, stores what it finds in #__updates and compares versions.

<!-- pkg_tallpine.xml (excerpt): the update server of the Tallpine package -->
<extension type="package" method="upgrade">
    <name>PKG_TALLPINE</name>
    <packagename>tallpine</packagename>
    <version>1.4.0</version>
    <updateservers>
        <server type="extension" priority="1" name="Tallpine Hiking Club Updates">https://updates.tallpine.example/pkg_tallpine.xml</server>
    </updateservers>
    <files folder="packages">
        <file type="component" id="com_tallpine">com_tallpine.zip</file>
        <file type="module" client="site" id="mod_tallpine_nexthikes">mod_tallpine_nexthikes.zip</file>
    </files>
</extension>

Source: Joomla Manual: Update Servers

The type is either extension (the URL is an update XML with updates and update elements) or collection (the URL is an extensionset file that lists several extensions and points to their individual files). priority sets the order of checks, and the name is displayed as given: the Manual advises against a language string there because it is not always translated.

The matching update XML for the package:

<?xml version="1.0" encoding="utf-8"?>
<updates>
    <update>
        <name>Tallpine Hiking Club package</name>
        <element>pkg_tallpine</element>
        <type>package</type>
        <version>1.4.1</version>
        <infourl title="Tallpine 1.4.1">https://updates.tallpine.example/changelog-1.4.1.html</infourl>
        <downloads>
            <downloadurl type="full" format="zip">https://updates.tallpine.example/pkg_tallpine-1.4.1.zip</downloadurl>
        </downloads>
        <security>3</security>
        <tags>
            <tag>stable</tag>
        </tags>
        <maintainer>Tallpine web team</maintainer>
        <targetplatform name="joomla" version="6\.[0-9]"/>
        <php_minimum>8.3</php_minimum>
        <sha256>CHANGE_ME_SHA256_OF_THE_ZIP</sha256>
    </update>
</updates>

Source: Joomla Manual: Update Servers

Points worth knowing about this file: targetplatform is a regular expression on the Joomla version; the element, type and, for plugins, folder and client must match the installed extension or no update appears; a <tag> of dev, alpha, beta, rc or stable sets the stability, and a missing tag means stable; php_minimum and supported_databases make an update visible but not installable on unsuitable servers; the optional sha256, sha384 and sha512 elements are compared with the downloaded package (the helper InstallerHelper::isChecksumValid()) and the update stops on a mismatch; and the zip file name has to match the download URL. The <security> element is new in 6.2 and is explained below.

The Update Sites screen

System → Manage → Update Sites lists the registered update servers. In the source of UpdatesitesModel the available filters are the enabled state, extension type, client, plugin folder, a search (a value such as id:42 selects an update site by number) and a download key filter. The toolbar actions behave as follows:

  • Enable / Disable toggles the enabled flag of the selected sites. Disabling the site of a third-party extension stops its update notices without uninstalling it.

  • Delete removes rows from #__update_sites, #__update_sites_extensions and #__updates. Core Joomla update sites are refused with an error.

  • Rebuild is a repair tool: it scans the manifests of installed site, administrator and API extensions, deletes non-core update-site rows and registers them again from the manifests, keeping any stored download key (extra_query) by matching the server location. It needs the Joomla Extension plugin to be enabled and the core.admin permission. Use it after a restore or when an extension shows no updates although its vendor offers them.

Update checks are cached; the Options of the Extensions component hold the cache time (an integer from 0 to 24, default 6) and the Minimum Stability (DEV, ALPHA, BETA, RC or STABLE, default STABLE). Lowering the stability on a production site makes release candidates and betas appear as normal updates; keep it at STABLE there and lower it only on a test copy.

Source: Joomla CMS source: UpdatesitesModel and Joomla CMS source: com_installer config.xml

Download keys

Commercial extensions usually restrict their update downloads to paying customers. The mechanism is the download key. The developer adds a dlid element to the extension manifest:

<!-- com_tallpine.xml (excerpt): the club sells a members' trail pack with a download key -->
<extension type="component" method="upgrade">
    <name>com_tallpine</name>
    <dlid prefix="dlid=" suffix="" />
    <updateservers>
        <server type="extension" name="Tallpine Premium Updates">https://updates.tallpine.example/premium.xml</server>
    </updateservers>
</extension>

Source: Joomla CMS source: com_installer InstallerHelper

When the manifest has a dlid element, Joomla treats the update site as supporting keys. The administrator pastes the key (a value such as CHANGE_ME_DOWNLOAD_KEY, never published) into the Download Key field of the update site, and Joomla stores it, wrapped in the manifest’s prefix and suffix, in the extra_query column of #__update_sites. At update time the stored string is appended to the update-server and download URLs as query data. The filter Supported / Missing / Valid on the Update Sites screen helps to find sites that need a key, and an update for an extension without a valid key cannot be downloaded. Operational notes: the key is a credential, so do not paste it into support tickets or screenshots; it lives in the database and therefore in every backup; and a rebuild keeps it but a delete does not. Older books such as Developing Extensions for Joomla! 5 (2023) describe the key from the developer side and remain accurate for the manifest syntax; the Manual’s Update Servers page does not cover it, so the source tree is the reference.

Updating extensions

System → Update → Extensions shows the result of the last check and a Check for Updates button. Select the entries and choose Update; the installer downloads each package from its downloadurl, validates the checksum if present, unpacks it and runs the adapter’s update path, including the update SQL and the update() method of the install script. Before updating:

  1. take a backup (Joomla has no core backup; the club uses a third-party tool and tests restores, see Backups and recovery);

  2. read the changelog linked from the update (the infourl and the changelog loaded from the manifest changelogurl);

  3. update on a staging copy when the extension is critical or the update is a major version;

  4. check the Database tab afterwards for schema problems.

Joomla itself is updated on a separate screen (System → Update → Joomla), and core can be updated automatically; extensions are not part of Automated Core Updates, so they remain a manual or scripted task. The Joomla! Update Notification plugin can email the administrators when an update exists; since 6.2 an additional task and mail templates for extension update notifications are under development, so check the 6.2.x release notes before relying on them.

The security severity flag (Joomla 6.2)

Joomla 6.2 lets an extension developer mark a release as a security release. The release announcement describes it as a flag with a severity from None to Critical, highlighted in the update view and on the dashboard so that administrators can spot such updates more easily. The implementation behind it, merged in July and August 2026 and also backported to Joomla 5.4, is:

  • a new optional element <security> in the update XML of an update, holding an integer: 0 None, 1 Low, 2 Medium, 3 High, 4 Critical. The scale follows common severity levels so that other tools can use it too;

  • a new nullable smallint column security in the table #__updates, filled during the update check (a database update script adds it);

  • a badge in the update view at administrator/index.php?option=com_installer&view=update and a notice on the Home dashboard;

  • the severity shown for an extension is the highest severity among all releases newer than the installed version, so a critical fix is not hidden behind a later ordinary release (the first merged version kept the last matching value, which was corrected before release).

For the administrator this means: a flagged update deserves priority, but the flag is information supplied by the update server, not a verdict by the Joomla project. An update server that never sends <security> simply shows no flag, and a malicious or compromised server could send any value, so continue to follow the Security Centre announcements and the Vulnerable Extensions List. For the developer, set the element only for releases that fix a vulnerability and keep the changelog specific. Entries that apply to several releases are listed separately in the update view.

Source: Joomla 6.2 release announcement and Joomla CMS pull request 48127: Support a security flag for updates

Disabling versus uninstalling

System → Manage → Extensions offers both operations, and they are not interchangeable.

Disable Uninstall

Effect

Sets enabled to 0 in the extensions table; the extension no longer runs.

Runs the adapter’s uninstall: removes files, the uninstall SQL, menu items, modules and the extensions row.

Files on disk

Stay on the server.

Removed according to the manifest.

Data

Kept.

Tables are usually dropped by the uninstall SQL, which many extensions omit; check.

Reversible

Yes, enable again.

Only by reinstalling, and data may be gone.

Security

A disabled extension’s files can still be reached by URL and exploited.

Removes the code; verify that nothing is left behind.

The Vulnerable Extensions section of the User Guide is explicit on the second point: unpublishing a module or removing a menu link is not enough, because the files stay on the server and can be called directly. The recommended procedure is to build a removal list from the extension’s XML manifest, uninstall through the installer, remove related modules, components and plugins, verify that files and tables are gone, and drop leftover tables only if you will not reinstall a safer version.

Source: Joomla User Guide: Vulnerable Extensions

Protected and locked extensions

The extensions table has two flags that stop mistakes. Extensions with protected set to 1 are part of the core and cannot be disabled; the Manage list shows them with a lock and offers a filter for protected and unprotected extensions. In the model ManageModel, publish() refuses a protected row with an "edit state not permitted" error, the default template and any template that is the parent of a child style cannot be disabled, and remove() refuses a row with locked set to 1 and reports a locked-extension message. The distinction matters in practice: you cannot disable the plugin that your login depends on, but the same safeguard means that a hasty "disable all plugins" in the database can lock you out. Do not set these flags on your own extensions merely to prevent removal; a package should be removable. The Core filter of the Manage screen separates extensions that ship with Joomla from the ones you added.

Source: Joomla CMS source: ManageModel

Vetting third-party extensions

Installing an extension means running someone else’s PHP on your server. A short checklist the Tallpine club applies before an install:

  1. Origin: use the vendor’s own site or the JED listing; avoid "nulled" copies of commercial extensions, which are the commonest way to receive a backdoor.

  2. Vulnerable Extensions List: check the extension name against the VEL maintained by the Joomla project. The User Guide notes that the list covers 240+ mostly old extensions and that an entry does not necessarily mean poor code, only that a flaw was found after release.

  3. JED Checker: this extension, installed like any other, inspects an extension zip for compliance with the JED standards, and is useful even for extensions that are not listed in the JED.

  4. Compatibility: look for explicit Joomla 6 support, a recent release and a maintained update server. Remember that Joomla 4 is end of life and 5.x receives only security fixes, so an extension that supports only older series is a risk.

  5. Reading the package: unzip it and read the manifest, the install script and the SQL, and look for obfuscated code, calls to remote servers and eval().

  6. Staging first: install on a copy, review the files created and the database tables, and test uninstall.

  7. Least privilege: restrict core.create and core.delete on com_installer to a few people, protect the administrator with MFA (see Security hardening, MFA and passkeys) and keep the file system read-only for the web user wherever the host allows it, so that a compromised extension cannot rewrite itself.

  8. Maintenance: uninstall what you do not use, subscribe to the Security Centre feed and review the update sites periodically.

Developers who want an extension listed should read Security in extensions and Build and CI for extensions, which cover the build of a clean package and automated checks.

Source: Joomla User Guide: The Joomla Extensions Directory

Installing from the command line and in containers

Production sites usually do not install extensions by clicking. The same com_installer code runs from the CLI and can be used from deployment scripts; see The Joomla command line interface for the available commands. In a Docker setup, see Local development with Docker and the site pages on Docker Compose for local development and Kubernetes cluster administration. A container filesystem is rebuilt on each deployment, so an extension installed through the administrator interface into a running container disappears with it; either bake the package into the image or mount persistent volumes for the extension folders, and keep the database in a managed service. When several web servers share one site, the install must happen on one node and the files must reach all nodes; where session or cache storage has to be shared, Redis is the usual choice.

Common errors and pitfalls

  • Updates never appear: the update site is disabled or was deleted, the server is unreachable, the stability filter is above the release tag, targetplatform does not match 6.2, or the cache time has not elapsed; use the Clear Cache button of the update screen or Rebuild.

  • Download key warnings: the key was not saved for that update site, or the prefix or suffix of the manifest does not match the stored string.

  • Update fails after download: checksum mismatch, a package name that differs from the URL, or the tmp folder is full.

  • Upgrading Joomla with old extensions: extensions using removed 5.x APIs break on 6.0 unless the Backward Compatibility 6 plugin is enabled; check this before the core upgrade (see Upgrading Joomla 5 to 6).

  • Documentation outdated: older books and tutorials, and the legacy wiki at docs.joomla.org, describe screens from Joomla 3 and early 4; the screen paths in this page are the current ones. The books Joomla! 4 Masterclass (2023) and Developing Extensions for Joomla! 5 (2023) predate the 6.2 security flag, the 5.1 TUF-verified core updates and Automated Core Updates, and target series that are end of life or security-only.

References