<< Back to Getting started page
This is a step by step guide on how to upgrade an installation of TYPO3 to a newer version.
notice - Note
notice - Note
- 1 General information
- 2 Upgrading to 4.5 Long Term Support
- 3 Upgrading to 4.6
- 4 Upgrading to 4.7
- 5 Upgrading to 6.0
- 6 Upgrading to 6.1
- 7 Upgrading to 6.2 Long Term Support
- 8 Upgrading to 7
- 9 Upgrading to 8.7 Long Term Support
Read the notes
You should not only go through the upgrade notes, which this page has for the version, to which you are updating, but also the notes for any intermediate versions, as these might also contain instructions you should follow.
You should also read the Release Notes of the main versions you go through when updating (e.g. 6.1.0 and 6.2.0). These documents contain a section called "Upgrading", which you should follow. See list of all Release Notes.
Upgrading to 4.5 Long Term Support
Situation: You want to upgrade from version 4.4 to 4.5 with Long Term Support.
Install new system extensions
Install the new system extensions, if you want them: Some functionalities, which could not be deactivated in former TYPO3 versions, are now system extensions, which you can deactivate if you don't use them. This applies to Filelist (File > Filelist), Perm (Web > Access), Func (Web > Func), Info (Web > Info) and Recordlist (Web > List).
Important: Update to UTF-8
From TYPO3 4.5, charsets other than UTF-8 are deprecated. Although TYPO3 still supports different charsets, the default is now UTF-8. In one of the later major releases of TYPO3, support for charsets other than UTF-8 will be dropped.
To find out which charset your installation is currently using, use the Update Wizard. See 18501: Core - Enable UTF-8 by default [Closed; assigned to Michael Stucki] for details.
You can find upgrading instructions in our page about Updating to UTF-8.
- Hints on UTF-8 and broken special chars can already be found in UTF-8 support.
- If you have problems with the error "BLOB/TEXT column 'identifier' used in key specification without a key length" popping up while migrating your database, try changing the $TYPO3_CONF_VARS['SYS']['multiplyDBfieldSize'] to 1. (Note that 1 is the default value and that values other than 1 are not necessary when your database uses UTF-8 encoding.)
Upgrading to 4.6
Situation: You want to upgrade from version 4.5 to 4.6.
Be aware that you need PHP 5.3 at least!
Important: Update your RTE configuration
From TYPO3 4.6 on, some TSconfig properties related to the RTE have become deprecated. Use the Upgrade Wizard in the Install Tool to check and adjust your TypoScript. Some of the replacements have to be done by hand as noted in the Upgrade Wizard.
Note that the developers have also adjusted the default configuration of the RTE to use the new properties instead of the old ones. If you've overridden any of the old properties, be sure to port the changes over to the new properties or you might get unexpected results since modification of the old defaults won't work anymore (because the old defaults are no longer used).
New Format for Translations
Older TYPO3 versions used locallang.xml files to translate the backend. In TYPO3 4.6, this has been changed to XLIFF. All old labels have been converted and new labels are provided solely in this format. For backwards compatibility the new translation packages also contain the old files.
- TYPO3 4.6 is subtitled "--rebase". This alludes to the fact that code that has been deprecated since at least TYPO3 4.4 has now been removed. Make sure to use the newest versions of all extensions, because old versions will likely use some of these formerly deprecated and now removed functions. By reading the deprecation log (located in typo3conf/, if it is enabled), you can find out about code using deprecated functionality.
Extensions that are not yet compatible
The following Extensions are not compatible with TYPO3 4.6:
- ics_awstats Version 0.5.3. -> Workarounds can be found in 31466: ICS AWStats - Remove deprecated "template->middle() " calls in backend module. [Accepted; assigned to Davide Caldelari] and in [ERROR: Cannot get content for issue "37122"]. With them ics_awstats is working with TYPO3 4.6. ics_awstats
Upgrading to 4.7
Situation: You want to upgrade from version 4.6 to 4.7.
As in TYPO3 4.6 you need PHP 5.3 at least.
Important: UTF-8 is the only supported character set
In earlier releases it has been announced that TYPO3 in the future will only support UTF-8 as the charset to work with internally. TYPO3 4.7 now is the first release, which only supports UTF-8.
- $TYPO3_CONF_VARS['BE']['forceCharset']: This option is not used anymore in TYPO3 4.7. If you have set it, TYPO3 will only work, if its value is "utf-8".
- If you already used the value "utf-8", you can just remove this line from your localconf.php. As this setting is no longer used, explicitly setting it is discouraged.
- All values other than "utf-8" will prevent TYPO3 from running and will trigger an error. If you used another value, please proceed to the Update Wizard in the TYPO3 Install Tool to update your configuration. Since the backend and the database will communicate "thinking" that they use the charset UTF-8, you must make sure that they really do. Otherwise you will create a charset mix in your database, which will be hard to fix later. See our page on UTF-8 conversion for information on how to fix your environment accordingly.
- $TYPO3_CONF_VARS['SYS']['setDBinit']: This option is not used anymore in TYPO3 4.7. If you have set it, TYPO3 will only work, if its value contains "SET NAMES utf8;".
- If your value already contains "SET NAMES utf8;", it's just fine. If that is all you have set there (might probably be), you should remove this line from your localconf.php file; TYPO3 4.7 makes sure that SET NAMES utf8; is sent to the database anyway.
- If you have set this option and your value does not contain SET NAMES utf8;, TYPO3 will not run and will only give out an error message. Your database, its connection and TYPO3 must then be migrated to UTF-8. Please change your setup accordingly. Our page on UTF-8 conversion contains all the information you might need to update your installation.
- Instructions on switching to UTF-8 can be found in UTF-8 support...
Upgrading to 6.0
Situation: You want to upgrade from version 4.7 to 6.0.
Be aware that you need PHP 5.3.7 at least!
Important: Changed localconf.php handling
Using the file typo3conf/localconf.php now is deprecated. Directly after completing the steps above you should use the Upgrade Wizard in the Install Tool and migrate your localconf.php file to the new format.
The wizard will create two new files in the folder typo3conf/: LocalConfiguration.php and AdditionalConfiguration.php.
- LocalConfiguration.php will contain all the settings from $TYPO3_CONF_VARS or $GLOBALS['TYPO3_CONF_VARS']. Additionally your database settings will be migrated into this file as well; you find them in the array with the key 'DB'.
- AdditionalConfiguration.php basically is an empty file, which is executed somewhen after LocalConfiguration.php. If you had additional stuff besides $TYPO3_CONF_VARS (this might be require_once-calls to some scripts you use or settings of enviroment variables) in localconf.php, they will be added to AdditionalConfiguration.php. During this process comments are not transferred, so take a look at localconf.php and copy all wanted comments to AdditionalConfiguration.php.
- localconf.php will be renamed to localconf.obsolete.php and is no longer needed. If everything works, you can safely remove it.
Important: Adjust user/group permissions
- If you gave your editors access to some image-related features, you have to update the access list of the BE user or of the BE group to allow them viewing and editing images in content elements. To do so give them access to the tables "File Storage", "File", "File Reference" and "File Collection".
- Also update the list with the allowed exclusion fields: If you granted the user/the group the right to edit the image position or the column number, you have to add the according rights "imageorient" and "imagecols" again.
- Compared to older versions nearly all files were moved in TYPO3 6.0. Although a compatibility layer has been brought in place, there is a slightly higher chance that you run into errors (e.g. if you are calling functions directly inside LocalConfiguration.php). If you get an error that a certain class or a function could not be found, open the file, which is mentioned in the error message and read the comment to find out, where this particular class has been moved. Then replace the call to the old class with a call to the new one.
Example: If you get an error that t3lib_div::getIndpEnv() could not be found, check the file t3lib/t3lib_div.php to find out, where the content of this file has been moved. Then replace the call with a call to TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv(), where this function is located now.
- If you used the setting mod.SHARED.colPos_list in Page TSconfig in order to display only selected columns in the page module, you have to replace this setting by a Backend Layout. This gives you more flexibility: E.g. it allows you to define different layouts and to let your editors pick the one they need on a page-by-page basis.
Upgrading to 6.1
Situation: You want to upgrade from version 6.0 to 6.1.
You need PHP 5.3.7 at least!
Important: System extension "statictemplates" has been removed
The system extension "statictemplates" was removed from the TYPO3 Core. If you used it, make sure to go through the according Upgrade Wizard in the Install Tool. It will import and install the extension from TER.
- Truncate all cf_* tables due to outdated cached information.
- EXT:tt_news: Version 3.4.0 (currently in TER) is not compatible with TYPO3 CMS 6.1; but there is a working (and patched) tt_news-version in the governmentpackage
- EXT:tt_news: updatescript of 3.4.0 is currently not compatible with TYPO3 CMS 6.1; if you upgrade from tt_news version 2.x, use the extensions updatescript before upgrading TYPO3 itself
Upgrading to 6.2 Long Term Support
Situation: You want to upgrade from version 6.1 to 6.2.
You need PHP 5.3.7 at least!
You must use TYPO3 4.5 or newer before you upgrade to TYPO3 6.2! Some upgrade wizards are not available anymore in 6.2 LTS, which makes it impossible to update from a version older than TYPO3 4.5 to TYPO3 6.2.
Information on LTS to LTS Upgrade
Several resources are available making an upgrade from TYPO3 4.5 to TYPO3 6.2 easier:
A smooth migration extension is available - it is especially useful for upgraders from TYPO3 4.5. It can be downloaded from TER (smoothmigration) or from its GitHub repository. Additional information on smooth migration is available in the Forge smooth migration project.
The Installation and Upgrade Guide has a new chapter on updating from TYPO3 4.5 to TYPO3 6.2.
- Truncate all cf_* tables due to outdated cached information.
- The folder t3lib/ has been removed; remove the according symlink!
Upgrading to 7
Situation: You want to upgrade from version 6.2 to 7 LTS.
You need PHP 5.5 at least!
You must use TYPO3 6.2 or newer before you upgrade to TYPO3 7 LTS! Upgrade wizards from before 6.2 LTS are not available anymore in 7, which makes it impossible to update from a version older than TYPO3 6.2.
An overview of all major changes in TYPO3 CMS is available here: https://docs.typo3.org/typo3cms/extensions/core/7.6/Index.html.
- The possibility of having a file called
typo3conf/extTables.phphas been deprecated. Instead of having code in this file, use extensions!
- If you are using content elements with
multimedia, the extension mediace will be added to your installation to handle these CTypes. Alternatively, in TYPO3 7, you can install the system extension fluid_styled_content, which is an experimental replacement for css_styled_content. For media content elements you can then use the "Text & Media" content element type of this extension. Note that fluid_styled_content will remove a number of CTypes, among them
textpic("Text & Images"), from the New Content Element wizard. When fluid_styled_content is installed and css_styled_content is not, there will be an upgrade wizard to migrate content elements, which use CTypes originally provided by css_styled_content. Note that you will most likely have to adjust your CSS styles in order to again get the Frontend output you want! For videos on YouTube, Vimeo and so on, another option is the "online media" feature of the Core; see 61799: Core - Improve the handling of media files [Resolved; assigned to Frans Saris] and its documentation.
- There is an Upgrade Wizard, which changes the startup modules of your Backend users. After you have run through the Upgrade Wizards, you might want to change the startup module for the Backend users again.
Upgrading to 8.7 Long Term Support
Situation: You want to upgrade from version 6.2 LTS to 8.7 LTS
Stepwise upgrade: You must use TYPO3 7.6 or newer before you upgrade to TYPO3 8.7 LTS! Therefore please upgrade from 6.2 to 7.6 first, then from 7.6 to 8.7 LTS. This involves running the LTS to LTS update wizard (see above), then the new 7.6 to 8.7 upgrade wizard. Plugins should be updated to the latest 7.6 compatible version first, then to the 8.7 version after the second upgrade. Note that the second upgrade is faster than the first!
You need PHP 7 at least for 8.7!