Installer in Joomla

1. The Basics

1.1 What com_installer Is

com_installer is the core Joomla component that manages the whole life of an extension: install, enable, disable, update, and uninstall. It does not live under its own top-level menu. Instead, it surfaces as a group of screens under System in the administrator.

It is itself an extension (a component named com_installer), and it is marked protected, so you cannot remove it by accident. Without it, you could not add or update anything else.

If a screen lets you add, update, or remove an extension, you are looking at com_installer.

1.2 Where to Find It

All of the installer screens sit under the System menu, split across three groups:

System
 ├─ Install
 │   └─ Extensions        (add new)
 ├─ Update
 │   └─ Extensions        (pending extension updates)
 └─ Manage
     ├─ Extensions        (enable / disable / uninstall, see every row)
     ├─ Update Sites      (where updates come from)
     ├─ Discover          (register files already on disk)
     ├─ Database          (check and fix the schema)
     └─ Warnings          (environment problems)

Each line is a different view of the same component. The URL gives it away: every one of these screens is index.php?option=com_installer&view=... in the administrator.

1.3 What It Is Not

com_installer handles extensions: the add-ons you bolt onto Joomla. It does not update the Joomla core itself. That is a separate component, com_joomlaupdate, reached from System → Update → Joomla. People confuse the two often, so keep the split in mind: com_installer for your add-ons, com_joomlaupdate for the CMS.

3. Installing Extensions

3.1 The Four Ways to Install

The install view offers four tabs. They all end in the same pipeline; they differ only in how the package reaches the server.

"Install from Web" is an app-store experience built into the backend. It talks to the Joomla Extensions Directory (JED) through a separate plugin, and you have to accept its terms once before it appears.

3.2 What "Install" Actually Does

Whatever method you pick, handing com_installer a package starts the same fixed sequence:

 1. Unzip the package into a temporary folder
 2. Find and parse the manifest   → read type, files, sql, scriptfile
 3. Run the script preflight()    → may abort the install
 4. Copy files to their homes     → components/, modules/, plugins/, media/
 5. Run the install SQL           → CREATE TABLE #__example...
 6. Register the PSR-4 namespace
 7. Write the #__extensions row + manifest_cache
 8. Register any update sites from the manifest
 9. Run the script postflight()   → seed data, show a message
10. Delete the temporary folder

If any step fails, com_installer rolls the whole thing back. You never end up with a half-installed extension on disk but missing from the database.

3.3 The Upload Size Limit

The most common install failure has nothing to do with Joomla. A large .zip can exceed PHP's upload_max_filesize or post_max_size, and the upload simply stops. When a big package will not upload, use Install from Folder (upload the unzipped files by FTP first) or Install from URL instead. The Warnings screen, covered later, reports these PHP limits so you can see them at a glance.

5. The Manage Screen

5.1 Your Control Panel

System → Manage → Extensions is the main view of com_installer. It lists every row in the #__extensions table: core and third-party, enabled and disabled, every type.

5.2 Protected and Locked

Two flags stop you from breaking the site by accident:

• Protected (protected = 1) means the extension cannot be uninstalled. Core extensions like com_content carry this flag.
• Locked (locked = 1) means the extension cannot be disabled or edited.

This is why the Manage screen refuses to let you remove com_installer itself, or disable the default language. The buttons are simply not offered for those rows.

5.3 Filtering Core Versus Non-Core

A fresh Joomla 6 install ships with around 150 extensions. To find your own add-ons among them, set the location and status filters, or use the "core" filter exposed in the API (described later). Most day-to-day work is on the small set of extensions you added yourself.

7. The Database Screen

7.1 Keeping the Schema in Sync

Manage → Database compares the SQL update files shipped inside each extension against what is actually in your database. When an update copied new files but the matching SQL never ran, the tables fall behind. This screen finds that gap.

• It lists every extension whose database structure is out of date.
• A Fix button replays the missing schema changes.
• It is the cure for the red "Database schema is out of date" warning on the home dashboard.

7.2 How It Knows: #__schemas

The check works through one small table, #__schemas, which records the highest schema version applied for each extension.

#__schemas
 extension_id   | version_id
 27  (com_content)   | 6.0.0
 10000 (com_example) | 1.1.0

Each extension's update folder holds SQL files named after versions, for example sql/updates/mysql/1.1.0.sql. After running them, Joomla writes the highest applied version into #__schemas. So #__extensions.manifest_cache stores the file version, while #__schemas stores the database version. When the two disagree, that is the warning, and Fix replays the missing SQL to close the gap.

9. Under the Hood (Developer View)

9.1 The Tables com_installer Touches

9.2 The Installer Class and Its Adapters

None of the screens contain the real install logic. They all call one framework class, Joomla\CMS\Installer\Installer, which orchestrates the whole sequence: unzip, parse the manifest, copy files, run SQL, write the row, fire events, clean up.

The clever part is that Installer does not know how any specific extension type is installed. It delegates that to a matching adapter. Each extension type has its own adapter class under Joomla\CMS\Installer\Adapter:

At install time, Installer reads the type attribute from the manifest, loads the adapter with that name, and hands the work over. This is why a component, a plugin, and a language pack all go through "the installer" yet each ends up in a different place with different database changes. Adding support for a brand-new extension type would mean writing a new adapter, not changing Installer itself.

Two more classes complete the picture: InstallerAdapter is the shared base every adapter extends, and InstallerScript is the base for an extension's own preflight/postflight script (covered in the extensions article).

9.3 Installer Events: Hooking Install and Update

com_installer fires events around every install, update, and uninstall. Any enabled plugin can listen, which lets it react when another extension is installed or updated. This is how commercial vendors add a download key at update time, with no change to the core.

// A vendor plugin adds its subscription key to the download URL:
public function onInstallerBeforePackageDownload(&$url, &$headers)
{
    if (str_contains($url, 'example.org')) {
        $url .= '&key=' . $this->params->get('download_key');
    }
}

9.4 Programmatic Install

You can drive the installer from your own code with the same Installer class. This is what scripts, migrations, and the CLI use under the hood; it picks the right adapter for you based on the manifest.

use Joomla\CMS\Installer\Installer;

$installer = new Installer();

// Install from an already-unzipped folder:
if ($installer->install('/path/to/unzipped/extension')) {
    // success
}

9.5 The Security Boundary

Installing an extension means copying and running code on your server, so com_installer is a real security boundary. It checks several things on every install:

• Access control: it defines its own ACL actions in access.xml, chiefly core.manage (use the screens) and core.admin (full control). Restrict these to administrators you trust. A user who can install extensions can effectively run any code on your server.
• CSRF tokens: every install, update, and uninstall request carries a one-time token, so an attacker cannot trick a logged-in admin into installing something through a forged link.
• A writable temporary directory: packages are unzipped into Joomla's tmp folder before anything is copied. If that folder is missing or not writable, the install fails early. The Warnings screen flags this.

11. Web Services API

11.1 Listing Extensions Over REST

com_installer exposes its Manage list through the Joomla Web Services API. With the API enabled and a token created under your user profile, you can read the installed-extension list from outside Joomla. The route is:

GET /api/index.php/v1/extensions

curl -H "X-Joomla-Token: <token>" \
     "https://example.test/api/index.php/v1/extensions"

11.2 Filtering the List

The endpoint accepts query parameters that match the screen filters, so you can narrow the result to what you care about:

curl -H "X-Joomla-Token: <token>" \
     "https://example.test/api/index.php/v1/extensions?core=false&type=plugin"

This is useful for monitoring: a script can pull the list of non-core extensions across many sites and flag anything disabled, outdated, or unexpected. Note that the public API covers reading the list; installing and updating still happen through the backend screens or the CLI.

11.3 The CLI Alternative

For automation that changes things, the Joomla command-line tool can check for and apply core updates and run scheduled tasks. For extension management, the backend screens and the framework Installer class remain the main tools.

13. Common Mistakes and Pitfalls

13.1 Confusing Extension Updates with Joomla Update

Symptom: You run System → Update → Joomla faithfully, but extensions stay outdated.

Fix: These are two components. Extension updates live under System → Update → Extensions (com_installer); the core lives under Update → Joomla (com_joomlaupdate). Check both.

13.2 A Package That Will Not Upload

Symptom: A large .zip fails or stalls on Upload Package File.

Fix: The file exceeds PHP's upload_max_filesize or post_max_size. Check the limits on the Warnings screen, then use Install from Folder or Install from URL instead.

13.3 No Update Notice Ever Appears

Symptom: A manually installed extension never offers an update.

Fix: It probably has no update site. Open Manage → Update Sites, confirm the site exists and is enabled, and use Rebuild if the list looks wrong.

13.4 The Update Seems Late

Symptom: A new version is out, but Joomla does not show it.

Fix: The update check is cached. Click Find Updates to force a fresh poll, or lower Update Cache Time in the Options. Also confirm Minimum Stability is not hiding a pre-release.

13.5 Copying Files Without Discover

Symptom: You uploaded an extension's folder by FTP, but Joomla does not see it.

Fix: Files on disk are not an installed extension until they have a #__extensions row. Run Manage → Discover to register them, or install the zip the normal way.

13.6 Ignoring the Schema Warning

Symptom: A red "Database schema is out of date" message that you keep dismissing.

Fix: It means an SQL migration did not run. Go to Manage → Database and click Fix before strange bugs appear.

15. Quick Reference

INSTALL       System → Install → Extensions (Upload / Folder / URL / Web)
MANAGE        System → Manage  → Extensions (enable / disable / uninstall)
UPDATE        System → Update  → Extensions (pending add-on updates)
CORE UPDATE   System → Update  → Joomla   (com_joomlaupdate, separate)
UPDATE SITES  Manage  → Update Sites (rebuild if updates go missing)
DISCOVER      Manage  → Discover  (register files already on disk)
DATABASE      Manage  → Database  (replay missing SQL with Fix)
WARNINGS      Manage  → Warnings  (PHP limits, writable folders)
OPTIONS       cachetimeout (6h) . minimum_stability (Stable)
REST          GET /api/index.php/v1/extensions ?core= &type= &status=
TABLES        #__extensions . #__update_sites . #__updates . #__schemas