Joomla! Documentation™

Content is Incomplete

This Page is a Candidate for Deletion

This notice should remain for a minimum of 1 week after it was placed on the page. If discussion is still ongoing, it should remain until a consensus is reached, after which the page will either be deleted or this notice removed. If you disagree with its deletion, please discuss your reasons on its associated talk page, as applicable.

Remember to check if anything links here and the page history before deleting.

Last edit by Ceford (talk · contrib) · Last edited on Sat, 27 May 2023 18:42:55 +0000

Description

This screen allows Joomla to be updated quickly by downloading the current update package from the Joomla code repository if there is an update. This setting is the default setting.

Update Images

• Update Screen when on the latest version:

You're on the latest version of Joomla, so no action required. If you have problems with Joomla it is possible to overwrite the latest Joomla core files. To do so click the button Reinstall Joomla core files and Joomla will install the latest core files.

Installation method can have the following values:

1. Write files directly
2. Hybrid (use FTP only if needed)
3. Write files using FTP

The first method is advised.

• The update screen when an update is available:

You're NOT on the latest version of Joomla, you can install the latest update from this screen. To do so click the button Install the Update and Joomla will install the latest update.

Installation method can have the following values:

1. Write files directly
2. Hybrid (use FTP only if needed)
3. Write files using FTP

The first method is advised.

• The screen while updating:

Troubleshooting

Joomla Update is a core component which is responsible for determining if there is a newer version of Joomla available for installation of your site, download it (or let you upload it) and install it. It has been available in Joomla since Joomla 2.5.1 and as a third party extension two years prior to that. You can access it at System, Update, Joomla.

The update process consists of several different steps. While every care has been taken to make this process as trouble–free as possible there's always a small chance that something may go wrong, typically due to a very restrictive server configuration or network conditions on a very small minority of sites.

The following troubleshooting instructions are organised by update step to make it easier to find the information you are looking for. Furthermore, it is an exhaustive resource, based on more than a decade of experience troubleshooting all possible (and some borderline impossible) problems with Joomla and extension updates. It lists problems which are extremely unlikely to occur. Don't let its length scare you; you are very unlikely to ever see any of these problems occur.

Determining if updates exist

Joomla will make a request to its update server over HTTPS and download an XML file provided by the Joomla project listing the latest available versions. The update server in use can be determined by going to System, Update, Joomla, clicking on Options and examining which update server is in use. You are recommended to use the Default update server to receive updates to your current major version of Joomla. Use Joomla Next when you want to upgrade your site to the next major version of Joomla — this is best done on a copy of your site to avoid any nasty surprises; not all third party extensions and templates will be compatible across major Joomla versions. The major version of Joomla is the first digit in the Joomla version, before the first dot. For example, the major version of Joomla 4.0.1 is 4.

If Joomla cannot determine that an update is available please check the following:

• The Joomla Update information is out of date in the database. Go to System, Update, Joomla and click on Check for Updates.
• The update sites information in Joomla is corrupt. Go to System, Update, Update Sites and click on Rebuild. Then go to System, Update, Joomla and click on Options. Select the Testing update channel. Click on Save & Close. Click on Options again. Select the Default or Joomla Next update channel — depending on your preference — and click on Save & Close.
• Your host prevents making outbound HTTPS requests at all or restricts them to predefined allowed IP addresses. Please ask them to allow outbound HTTP requests to https://update.joomla.org This is a CDN, meaning that the exact IP address will be different depending on where the world you are trying to access this URL from. Do tell your host; they will know what to do with this information.
• Your host may have an outdated SSL library which does not understand the modern TLS certificates used by the Joomla update CDN. Please ask your host about it.

Determining if third party software is compatible with the new version you are about to install

Joomla does not have a magical way of evaluating third party code for compatibility. Its report is based solely on the extension information kept in Joomla's #__extensions table, the update sites provided by the installed extensions and the update information provided by the developers of third party extensions including but not limited to which version of their software is compatible with which version of Joomla.

If the information displayed is incorrect please check the following:

• What is the minimum stability for extension updates? Go to System, Update, Extensions and click on Options. The ‘Minimum Extension Stability’ determines which is the minimum stability level of a third party software that Joomla will take into account when evaluating compatibility. For example, if this option is set to Stable but only a beta version of a third party extension is compatible with the Joomla version you want to upgrade to Joomla will tell you that there is no compatible version of the third party extension available.
• The update information may be out of date. Go to System, Update, Extensions and click on Check For Updates. Then go back to System, Update, Joomla and see if the extension now appears as compatible or if you are told than a compatible update to it is available.
• The update sites information in Joomla is corrupt. Go to System, Update, Update Sites and click on Rebuild. Then go to System, Update, Joomla and click on Options. Select the Testing update channel. Click on Save & Close. Click on Options again. Select the Default or Joomla Next update channel — depending on your preference — and click on Save & Close.
• Your host prevents making outbound HTTP/HTTPS requests at all or restricts them to predefined allowed IP addresses. This will prevent Joomla from retrieving update information from third party update sites. First go to System, Update, Update Sites. Below each update site you will see its URL. Make a list of those URLs. Then ask your host to allow your site to make requests to these URLs. Please note that some of these URLs may point to a CDN, meaning that the exact IP address will be different depending on where the world you are trying to access this URL from. Do tell your host; they will know what to do with this information.
• Your host may have an outdated SSL library which does not understand the modern TLS certificates used by most third party extension developers' update sites. Please ask your host about it.
• You may have “orphaned” extensions. Most modern Joomla extensions are delivered as ‘package’ type extensions which include two or more related extensions. When installing a package extension Joomla records a package extension in its database. It then records the package ID to each of the installed extensions from that package in the database. The update information is provided for the package, not each individual extension. This association may break if you used Discover to install the extensions, extracted the package and installed the separate extensions directly, Joomla failed to record the package ID for each extension when installing the package (most likely because an error occurred) or your site has been upgraded from an old version of Joomla which predates the use of packages in extensions. In this case even updating the extension will NOT update the package association. There is currently no solution to this except determining manually the compatibility of extensions with each Joomla version.
• In some cases the number of requests Joomla sends to your server as it determines compatibility for each extension may overwhelm the server and trigger a Denial of Service protection. In this case some or all of the extensions will appear as of indeterminate compatibility status. Unfortuantely, you will have to check the compatibility of each extension manually against the information published by extension's developer.

Downloading the update

Joomla will need to download its update package, a ZIP file which is very similar to the Joomla installation ZIP file but without the web installer (the `installation` directory). This could fail for a few reasons:

• The ZIP file is rather big. Joomla 4 update packages are around 25MiB. If your server is slow, overwhelmed or has poor connectivity with GitHub — where Joomla update packages are downloaded from — it may take a long time to download the package. If that time is longer than your server's PHP maximum execution time, its maximum CPU usage limit (as determined by ulimit -t in the server command line), the PHP-FPM timeout or the web server's timeout the download will fail and you will see an error page. You will have to ask your host for help with that.
• You may not have enough free space on your site. You need enough space to store the compressed update ZIP file and its extracted files. As a rule of thumb, you need about 50–60 MiB of free space for Joomla Update to work correctly. Do note that the free space reported by your hosting control panel is not always realtime, i.e. it may ‘lag’ several minutes or hours behind the actual disk space usage on your site. Moreover, further limits may be imposed by your host. If unsure, please ask your host.
• Your host prevents making outbound HTTPS requests at all or restricts them to predefined allowed IP addresses. Please ask them to allow outbound HTTP requests to `https://github.com`. This is a CDN, meaning that the exact IP address will be different depending on where the world you are trying to access this URL from. Do tell your host; they will know what to do with this information.
• Your host may have an outdated SSL library which does not understand the modern TLS certificates used by GitHub. Please ask your host about it.

Extracting the update

After the update ZIP file has downloaded Joomla needs to extract it on your site. Since Joomla is effectively replacing itself and because this process does take some time to complete it cannot happen within Joomla itself. Instead, a separate file (administrator/components/com_joomlaupdate/extract.php) is used to perform the update. This file is inert except when an update is in progress.

You may get an error during the extraction for one of the following reasons:

• You cannot access the extract.php file because of a server protection e.g. a customised .htaccess file on Apache and Litespeed servers. Try accessing https://www.example.com/administrator/components/com_joomlaupdate/extract.php from a web browser, where https://www.example.com/ is to be replaced with the URL to your site. You should see the message {"status":false,"message":"Invalid login"} If you see anything else you are being forbidden from accessing this file.
• If you can access the file but extracting the update fails immediately there is a different server protection on your site which prevents the request to `extract.php` from being handled by that file. Please contact your host about this.
• If you are using CloudFlare go to Rules and create a new Page Rule. Set the If URL Matches to */administrator/components/com_joomlaupdate/extract.php and Then The Settings Are to “Disable Security” and on a new line ”Cache Level”, ‘Bypass’. Set the Order to First. Click on Save and Deploy. This ensures that CloudFlare will not try to block the update extraction.
• The update ZIP file is corrupt or truncated. This could happen if downloading the update file failed with an error. Go back and retry. See also the previous section.
• If you are using upload and update i.e. you uploaded the update ZIP file yourself please make sure that you are using only the official Joomla Update ZIP files. The extraction script only supports a subset of the ZIP archive format used by the official update ZIP files.
• Did you run out of disk space? Please check the section above.
• Is the ownership and permissions of all files correct? Joomla needs write access to all of its files and folders. If unsure, ask your host. There is no specific set of “good” permissions! The permissions needed depend on the ownership of your files and which system user the web server runs under.
• Did you lose network connectivity or your network has very high latency? It's possible that the request fails because of that.
• The extraction takes place by making consecutive requests to the aforementioned extract.php file. Each request is set up to take between 3 and 4 seconds. The process repeats until the entirety of the update file has been extracted. On some servers this cadence of requests to the same file from the same IP address may trigger the server's security. On other servers it may trigger a different server protection, e.g. a maximum PHP time limit, a maximum CPU usage limit or another server timeout. On even fewer servers running on CloudLinux it could trigger a server memory outage situation if your server was already running low on memory. You need to contact your server about that; there is nothing you can do yourself to work around these server limitations.

Finalising the update

This is a two step process.

Right after the update ZIP file has been extracted a final step will run which removes old files. When upgrading to a new major version of Joomla the list of files to remove is pretty big and the process may timeout. Moreover, the point made in the previous section about ownership and permissions of files is important here too; Joomla needs write permissions to the old files and folders it has to remove. If this step fails you can resume it from the command line. Go into the cli folder and run php joomla.php update:joomla:remove-old-files If you cannot do it yourself ask your host to do it for you. You will also need to follow the workaround for the next step.

Finally, Joomla reloads and you are logged back into the administrator interface. At this point Joomla updates its database tables and performs any database administration tasks. If this fails you can resume the process by going to System, Maintenance, Database. Select Joomla CMS from the list and click on Update Structure.