Upgrading to a major release using Composer

Upgrade the PHP version first during major TYPO3 upgrades

Each TYPO3 version is compatible with at least two PHP versions, with some overlap. When upgrading to a new major TYPO3 version, first update PHP to the highest version your current TYPO3 version supports.

Test your project thoroughly. Fix any PHP-related issues in custom extensions and configurations before proceeding.

Next, upgrade TYPO3 while keeping the PHP version unchanged. This will help you to identify whether errors stem from the TYPO3 core or from PHP.

During development, tools like DDEV make it easy to switch PHP versions. Some hosting environments also allow multiple PHP versions. Try changes in a staging or relaunch setup before updating production.

Check each currently installed extension for compatible versions

Many TYPO3 extensions are compatible with two major TYPO3 versions. If an extension in your project follows this pattern, update it to the highest version still compatible with your current TYPO3 version. This will help you identify whether issues are caused by the TYPO3 core or the extension itself.

Tip

Check each extension's changelog (if it exists) before you update an extension.

Ensure all extensions you use are available for the TYPO3 version you're upgrading to. If a third-party extension isn’t ready, consider supporting or sponsoring the author to update it. Some agencies offer early access to updated extensions for a fee.

If an extension is no longer maintained, look for alternatives. Abandoned extensions are sometimes forked and maintained by others. As a last resort, you can fork the extension yourself or hire a developer to update it for you.

All custom extensions, including your custom site package (theme), need to be updated by yourself.

Review Core changes in the Changelog before upgrading

TYPO3 system extensions are part of the Core and may change between versions. Some may be merged, added, deprecated, or removed.

Before starting a major upgrade, make sure to review the TYPO3 changelog for changes to system extensions. This will help you plan ahead for any required changes.

Running `composer require` with new major version dependencies

Warning

Never try the following on a production system. Work locally and use a deployment strategy.

If you have to work on the server, work on a copy of the production website including a copy of the database

To upgrade a Composer package, run composer require with the package name and version number.

For example, to upgrade typo3/cms-backend run composer require typo3/cms-backend:^13.4.

When upgrading to a new major release, each of TYPO3's packages will need to be upgraded.

Given that a typical installation of TYPO3 will consist of a number of packages, it is recommended that the Composer Helper Tool be used to help generate the Composer upgrade command.

Assuming that the packages below are installed locally, the following example would upgrade each of them to version 13.4.

composer require --update-with-all-dependencies "typo3/cms-adminpanel:^13.4" \
"typo3/cms-backend:^13.4" "typo3/cms-belog:^13.4" "typo3/cms-beuser:^13.4" \
"typo3/cms-core:^13.4" "typo3/cms-dashboard:^13.4"  "typo3/cms-extbase:^13.4" \
"typo3/cms-extensionmanager:^13.4" "typo3/cms-felogin:^13.4" "typo3/cms-fluid-styled-content:^13.4" \
"typo3/cms-filelist:^13.4" "typo3/cms-filemetadata:^13.4" "typo3/cms-fluid:^13.4" \
"typo3/cms-form:^13.4" "typo3/cms-frontend:^13.4" "typo3/cms-impexp:^13.4" \
"typo3/cms-info:^13.4" "typo3/cms-install:^13.4" "typo3/cms-linkvalidator:^13.4" \
"typo3/cms-lowlevel:^13.4" "typo3/cms-reactions:^13.4" "typo3/cms-recycler:^13.4" \
"typo3/cms-rte-ckeditor:^13.4" "typo3/cms-seo:^13.4"  "typo3/cms-setup:^13.4" \
"typo3/cms-sys-note:^13.4" "typo3/cms-t3editor:^13.4" "typo3/cms-tstemplate:^13.4" \
"typo3/cms-viewpage:^13.4" "typo3/cms-webhooks:^13.4"

A typical TYPO3 installation is likely to have multiple third-party extensions installed and running the above command can create dependency errors.

For example, when upgrading from TYPO3 v12 LTS to v13 LTS an error can occur stating that "helhum/typo3-console": "^8.1" is only compatible with v12 LTS, with the new version ^9.1 supporting TYPO3 v13 LTS.

For each of these dependency errors, add the version requirement "helhum/typo3-console:^9.1" to the end of your composer require string and retry the command.

Sometimes version upgrades disrupt Composer’s file structure. If issues persist, delete the vendor folder and possibly also composer.lock. Then manually adjust composer.json and run:

composer install

Once the upgrade is complete, there are a set of tasks that need to actioned to complete the process. See Post-upgrade tasks.