Pre-upgrade tasks

Before starting the upgrade check your system for compatibility with a newer TYPO3 version.

  • Before you upgrade to the next major version, make sure you have run all Upgrade Wizards of the the current TYPO3 major version.

  • Check for deprecations: Enable the deprecation log and let it log all deprecations for a while.

  • Alternatively (or additionally) run the extension scanner and handle deprecations (below).

  • Check installed extensions for versions compatible to the target TYPO3 version

  • Try the upgrade on a development system first or create a parallel instance

Check that all system requirements for upgrading are met:

Make A Backup

Make a backup first! If things go wrong, you can at least go back to the old version. You need a backup of

  • all files of your TYPO3 installation (by using FTP, SCP, rsync, or any other method)

  • the database (by exporting the database to an SQL file)

Also you may prefer to upgrade a copy of your site first, if there have been a lot of changes and some of them might interfere with functions of your site. See the changelog to check that.

For more detailed information about TYPO3 backups see Backup strategy in TYPO3 Explained.

Update Reference Index


As the reference index might take some time, especially on instances not running it regularly, an upgrade via command line (CLI) is recommended to avoid a timeout.

Without command line

Still in your old TYPO3 version, go to the System > DB check module and use the Manage Reference Index function.

Click on Update reference index to update the reference index. In case there is a timeout, and you do not have CLI access (see above) you might have to run the update multiple times.


The lowlevel system extension must be installed for the mentioned backend module.

Check the ChangeLog

In addition to the deprecations you may want to read the information about important changes, new features and breaking changes for the release you are updating to.

The ChangeLog is divided into four sections "Breaking Changes", "Features", "Deprecation" and "Important". Before upgrading you should at least take a look at the sections "Breaking Changes" and "Important" - changes described in those areas might affect your website.


Breaking changes should be of no concern to you if you already handled the deprecations before upgrading.

The detailed information contains a section called "Affected Installations" which contains hints whether or not your website is affected by the change.

There are 3 different methods you can use to read the Changelogs:

  1. Look through the changelogs online. This has the advantage that code blocks will be formatted nicely with syntax highlighting.

  2. Read the Changelogs in the backend: Upgrade > View Upgrade Documentation. This has the advantage that you can filter by tags and mark individual Changelogs as done. This way, it is possible to use the list like a todo list.

  3. Read the changelog in the Extension Scanner (as explained above).

Upgrade Analysis

The "Upgrade Analysis" in the Install Tool

Resolve Deprecations

If you notice some API you are using is deprecated, you should look up the corresponding changelog entry and see how to migrate your code corresponding to the documentation.

Since TYPO3 v9 an extension scanner is included, that provides basic scanning of your extensions for deprecated code. While it does not catch everything, it can be used as a base for an upgrade. You can either access the extension scanner via the TYPO3 admin tools (in the Backend: Module "Upgrade" > "Scan Extension Files") or as a standalone tool (

The extension scanner will show the corresponding changelog which contains a description of how to migrate your code. See Check the ChangeLog for more information about the Changelogs and how to read them.

In addition you can use the tool typo3-rector to automatically refactor the code for a lot of deprecations.


TYPO3 aims at providing a reliable backwards compatibility between versions:

  • Minor versions are always backwards compatible - unless explicitly stated otherwise (for example in case of security updates)

  • Major versions may contain breaking changes - normally these are deprecated one major version in advance

  • Most breaking changes usually happen in the first Sprint Release

If PHP classes, methods, constants, functions or parameters are to be removed, they will be marked as deprecated first and not removed until the next major release of TYPO3. For example: a method that gets deprecated in version 9.4.0 will remain fully functional in all 9.x.x releases, but will be removed in version 10.

This strategy gives developers sufficient time to adjust their TYPO3 extensions, assuming many agencies upgrade from one LTS release to the next (usually 1.5 years).

Convert Global Extensions

Changed in version 12.0: The support of global extensions was removed with TYPO3 v12.0. Convert them to local ones.

Global extensions used to be saved in folders inside typo3/ext/, such as typo3/ext/news. In current versions of TYPO3, this location should no longer be used. Instead, use local extensions below typo3conf/ext/.

To convert a global extension to a local one, do the following:

  • Go to the Admin Tools > Extensions backend module.

  • Uninstall the global extension.

  • Delete the files of the extension from typo3/ext/, including the directory of that extension itself.

  • Reinstall the extension from the TYPO3 Extension Repository, which will put it into typo3conf/ext/.


In earlier versions of TYPO3 global extensions were an easy way of sharing extensions between multiple TYPO3 instances. Nowadays, the recommended way of installing and maintaining extensions is via Composer, where you may use different strategies to achieve the same goal. One example would be to use "path repositories" in your composer.json file