Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Upgrade

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Core Team (category Core Team)

<< Back to Getting started page

[edit]

This is a step by step guide on how to upgrade an installation of TYPO3 to a newer version.

Note If a step is not understandable, you can note that here!

Contents

General information

Think of active users

Think of users who might want to do any changes during your upgrading and/or fallback. Inform them before you start!

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)

Which version to use

Generally (when there are no backwards compatibility concerns), you should always use the most recent version of a branch.

You can download the source code from typo3.org.

Upgrading versions older than TYPO3 4.1

If you're using a version older than 4.1 (4.0, 3.8.x or below), first install the most recent version from the 4.1 branch.

Upgrading current versions (4.1 or greater)

Install the newest version from the branch you want (4.2, 4.3, 4.4 or 4.5).

Read the Release Notes for the main versions

You should read the Release Notes of the main versions you go through when updating (e.g. 4.2.0 and 4.3.0). These documents contain a section called "Upgrading", which you should follow.

See list of all Release Notes.

Common procedures

Depending on your situation you might have to do some or all of the following during your upgrade. We put those general information in front so that we don't have to repeat them all over. Go on with the special section which applies to the update you want to do. But if the special instructions refer to this section, follow the procedures explained here.

Converting global to local extensions

Global extensions used to be saved in folders inside typo3/ext/, such as typo3/ext/realurl. In current versions of TYPO3, this location should no longer be used. Instead, save local extensions in typo3conf/ext/[Ext-Name]. (Note typo3conf/ instead of typo3/.)

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

  1. Go to the Extension Manager.
  2. Uninstall the global extension.
  3. Delete the files of the extension from typo3/ext/[Ext-Name], including the directory typo3/ext/[Ext-Name] itself.
  4. Reinstall the extension from TER as local.

Installing a new TYPO3 version ("upgrading TYPO3 core source code")

If you're using symbolic links for the TYPO3 core (see below, *nix only):

  • Extract the source code package alongside the old version directory
  • Unlink the old typo3_src folder
  • Link the new typo3_src folder to the new version's directory

If the TYPO3 core is physically located directly inside the web root:

  • Unlink the folders
    • typo3/
    • media/
    • tslib/
    • t3lib/
    • and the files showpic.php and index.php
  2. Copy the extracted contents of the new source code into the same location where you've just deleted the old source code.

Upgrading the database after installing a new version

  1. Enter the install tool.
    • You can access it by appending typo3/install to the URL of your site. If you see a message saying that it has been disabled, either create an empty file called ENABLE_INSTALL_TOOL in the folder typo3conf/ or in the BE via "User Tools"->"User Settings"->"Admin Functions"->"Create Install Tool Enable File". Refresh the page and you should be able to log in.
  2. In section "Database Analyzer":
    • Click "Update required tables"
    • Click "COMPARE" and "IMPORT" and apply the proposed changes.
  3. In section "Basic Configuration":
    • If no Encryption Key is set, set an Encryption Key. (It is likely that the Encryption Key is not set, if you are updating from a TYPO3 version prior to 4.1.)
  4. In section "Upgrade Wizard":
    • Set the compatibility version. It is optional to set this to the version number of your new TYPO3 version. Doing so, however, enables you to use the new features concerning the frontend output (like new default styling rules from CSS Styled Content). Changing this can affect the frontend output!
  5. In section "Edit files in typo3conf/":
    • Delete all temp_CACHED* files.

Upgrading from 3.8.1 ...

... to 4.1 on a Windows-system

Do the following in order:

  1. Change all global extensions to local ones (see "Common procedures" above).
  2. Install new source code (see "Common procedures" above).
  3. Upgrade database (see "Common procedures" above).

Remember to clear your PHP opcode cache after upgrading if you have any.

Please also read the TYPO3_4.0 Release notes.

... to 4.1 on a UNIX-system using a shell

Environment:

  • TYPO3 is installed on a *nix system (i.e. Linux, FreeBSD)
  • Existing TYPO3 is set up in the webroot folder
  • TYPO3 will be set up using symlinks to make upgrading easier: You will just have to change the link pointing to the folder with the source code in order to use a new version.


Current Environment: 

$ pwd
/home/typo3/

$ cd public_html/

$ ls -la
drwxr-xr-x  7 typo3  typo3        512 Feb  7 05:02 .
drwxr-xr-x  4 typo3  typo3        512 Apr  8 20:01 ..
-rw-rw----  1 typo3  www         4987 Nov 12 11:41 INSTALL.txt
-rw-rw----  1 typo3  www          608 Nov 12 11:41 Package.txt
-rw-rw----  1 typo3  www         8118 Nov 12 11:41 README.txt
-rw-rw----  1 typo3  www         1212 Nov 12 11:41 RELEASE_NOTES.txt
-rw-rw----  1 typo3  www         4957 Nov 12 11:40 _.htaccess
-rw-rw----  1 typo3  www           46 Nov 12 11:40 clear.gif
drwxrwx---  5 typo3  www          512 Feb 11 07:49 fileadmin
lrwxr-xr-x  1 typo3  typo3         18 Nov 12 11:40 index.php -> tslib/index_ts.php
lrwxr-xr-x  1 typo3  typo3         11 Nov 12 11:40 media -> tslib/media
lrwxr-xr-x  1 typo3  typo3         17 Nov 12 11:40 showpic.php -> tslib/showpic.php
lrwxr-xr-x  1 typo3  typo3         15 Nov 12 11:40 t3lib -> typo3_src/t3lib
lrwxr-xr-x  1 typo3  typo3         15 Nov 12 11:40 typo3 -> typo3_src/typo3
lrwxr-xr-x  1 typo3  typo3         18 Feb  7 05:02 typo3_src -> ./typo3_src-3.8.1/
drwxrwx---  5 typo3  www          512 Nov 12 11:41 typo3_src-3.8.1
drwxrwx---  3 typo3  www          512 Apr  3 07:26 typo3conf
drwxrwx---  6 typo3  www          512 Mar 10 07:56 typo3temp
drwxrwx---  9 typo3  www          512 Feb 11 08:22 uploads

Before you upgrade:

  1. Change all global extensions to local ones (see "Common procedures" above).


Upgrade:

1.) Copy the new TYPO3 4.1 source code typo3_src-4.1.tar.gz into the site location and decompress it:

shell script:
cp typo3_src-4.1.tar.gz public_html/
tar xvzf typo3_src-4.1.tar.gz

</pre>

2.) Remove the symbolic links to the old TYPO3 source code and create a new symlink to typo3_src:

shell script:
cd public_html
rm typo3_src
ln -s typo3_src-4.1 typo3_src

2.1 If you use a separate TYPO3 source code directory:

This has the advantage of being able to host several TYPO3 installations using the same source, thus saving space (and RAM in case you're using an opcode cache like APC). If you choose to keep the TYPO3 source code in a separate directory, this step would be made with something like this:

shell script:
$ cd public_html
rm typo3_src
ln -s ../typo3_src-4.1 typo3_src

(Essence: The symlink you create here always has to point to the TYPO3 source folder, no matter where it is located.)

3.) Clean up unused symbolic links: (They are no longer needed for the new version.)

shell script:
pwd
/home/typo3/public_html
 
rm media
rm t3lib 
rm tslib
rm showpic.php
rm index.php

4.) Create new symlinks:

shell script:
pwd
/home/typo3/public_html
 
ln -s typo3_src/index.php index.php
ln -s typo3_src/typo3 typo3
ln -s typo3_src/t3lib t3lib

(Creating the new symlinks in 2 steps (numbers 2 and 4 here) makes following updates easier, because you will just have to change the link pointing to the folder with the source in order to use the new version.)


Upgraded Environment: 

$ ls -la
drwxr-xr-x  8 typo3  www      512 Apr  9 22:39 .
drwxr-xr-x  4 typo3  typo3   512 Apr  8 22:41 ..
-rw-rw----  1 typo3  www     4987 Nov 12 11:41 INSTALL.txt
-rw-rw----  1 typo3  www      608 Nov 12 11:41 Package.txt
-rw-rw----  1 typo3  www     8118 Nov 12 11:41 README.txt
-rw-rw----  1 typo3  www     1212 Nov 12 11:41 RELEASE_NOTES.txt
-rw-rw----  1 typo3  www     4957 Nov 12 11:40 _.htaccess
-rw-rw----  1 typo3  www       46 Nov 12 11:40 clear.gif
drwxrwx---  5 typo3  www      512 Feb 14 06:34 fileadmin
lrwxr-xr-x  1 typo3  www       19 Apr  8 22:55 index.php -> typo3_src/index.php
lrwxr-xr-x  1 typo3  www       15 Nov 12 11:40 t3lib -> typo3_src/t3lib
lrwxr-xr-x  1 typo3  www       15 Apr  9 22:38 typo3 -> typo3_src/typo3
lrwxr-xr-x  1 typo3  www       13 Apr  9 22:38 typo3_src -> typo3_src-4.1
drwxrwx---  4 typo3  www      512 Apr  8 22:40 typo3_src-3.8.1
drwxr-xr-x  5 typo3  www      512 Apr  7 00:18 typo3_src-4.1
drwxrwx---  3 typo3  www      512 Apr  9 22:50 typo3conf
drwxrwx---  6 typo3  www      512 Feb 14 06:37 typo3temp
drwxrwx---  7 typo3  www      512 Feb 12 00:39 uploads
  1. Upgrade database (see "Common procedures" above).

Miscellaneous

More instructions for upgrading

  • The Web-Empowered Church offers a tutorial titled Upgrading from TYPO3 3.x to 4.x.. It includes both textual instructions and detailed step-by-step flash movies created with Wink for an update on a *nix or Windows system.

Updating extensions

It is important to correct errors you might see in the BE. Most likely these are caused by outdated extensions.

If you get PHP errors, look at the file where the first error occurs in and uninstall the corresponding extension in the Extension Manager.

For example you might have used a rich text editor in TYPO3 3.8. From TYPO3 4.1 on there is one included by default so that you should check if the RTE still works correctly. If not uninstall your old version and delete its files. Empty all caches in TYPO3 and check it again.


Trouble with click-enlarge images and RealURL

From 3.8.1 to 4.0 the file showpic.php has been replaced by typo3/sysext/cms/tslib/showpic.php.

If you use RealURL and didn't end the base (site) URL in TypoScript with a slash:

TS TypoScript:
config.baseurl = http://www.yourdomain.org

you will get an error when you open the popup: "www.yourdomain.orgindex.php is not found".

Add a slash to fix this:

TS TypoScript:
config.baseurl = http://www.yourdomain.org/

Wrong page tree rendering after upgrade to TYPO3 4.1

The way how the page tree is displayed was changed for TYPO3 4.1. After the upgrade it might expose rendering errors. Delete the browser cache to use the new CSS.

Upgrading from 4.0 to 4.1 without using a shell

This describes how to migrate from TYPO3 4.0 to 4.1 without using a shell. You only need an FTP client and FTP access to your server.

Situation:

TYPO3 is installed in the webroot folder without any symlinks.

Extensions:

  • Change all globally installed extensions to local ones
    • Start Extension Manager
    • Uninstall extension
    • Delete the files of the extension in typo3/ext/[Ext-Name]
    • Reinstall extension from TER as _local_


Copy the TYPO3 source:

  • Copy the whole content of the source file to the webroot.


Follow the instructions on http://webempoweredchurch.org/support/classes/upgrading-typo3

  • Step 3 to 6 only
  • Comments to Step 3: Maybe the Install Tool has to be started manually via <yourdomain>/typo3/install/index.php
  • Comments to Step 4: Clear cache on the end with two links (see section "Admin functions")


Complete the update:

  • Log into Backend
  • Run Install Tool
    • Set the compatibility-version with the "Upgrade Wizard" to 4.1 (This can affect the output of your website in the frontend!)
    • Under "Basic Configuration" -> "Encryption Key" set the Encryption-key
  • Delete or rename /typo3/typo3conf/ENABLE_INSTALL_TOOL
  • Optional: Increase performance by renaming some _.htaccess-files: See list on http://typo3.org/development/articles/release-notes-41/page/4/


Cleanup:

  • Take the opportunity to remove all unused extensions now!

Upgrading from 4.1 to 4.2

Situation: You want to upgrade from version 4.1 to 4.2.

Be aware that you should use PHP 5.2 at least!

As long as enterprise Linux distributions like the ones from Novell or RedHat have not been published with PHP 5.2 built in, TYPO3 4.2 will stay compatible with PHP 5.1 as promissed here. Afterwards PHP 5.2 might be needed as requirement.

In short

  1. Change all global extensions to local ones (see "Common procedures" above).
  2. Install new source code (see "Common procedures" above).
  3. Upgrade database (see "Common procedures" above).

Notes


Extensions that are not yet compatible

The following Extensions are not compatible with TYPO3 4.2:

  • dam Version 1.0.11. -> Upgrade to dam 1.0.13 dam
  • pmkisac Version 1.2.0. pmkisac
  • dam_catedit Version 1.0.6. dam_catedit Popup menu is not working in BE
  • pagetreetools Version 1.0.3. pagetreetools produces error output in the pagetree area
  • kickstarter Version 0.3.8. kickstarter produces error when editing existing extension. -> Upgrade to 0.4.0
  • pmktextarea Version 0.2.0 pmktextarea causes page tree click menu not to work, because prototype.js will not be loaded. -> Upgrade to 0.3.0


Upgrading to 4.3

Situation: You want to upgrade from version 4.2 to 4.3.

Be aware that you need PHP 5.2 at least! TYPO3 4.3 is no longer compatible with PHP 5.1.

The PHP extension filter needs to be installed. For a full list of requirements see here.

In short

  1. Change all global extensions to local ones (see "Common procedures" above).
  2. Install new source code (see "Common procedures" above).
  3. Upgrade database (see "Common procedures" above).

After upgrading

  • Upgrade the extensions you use. Delete unused extensions.
  • Go to the Extension Manager and open the section "Translation Handling". Check and update your translations. In TYPO3 4.3 all modules are translatable. (The translations are available, after the translation team for your language has translated the texts.)
  • Delete obsolete TSConfig commands esp. auth.BE.redirectToURL = alt_main.php?module=[web_layout] in UserTSConfig
  • Here is an error document which explains, how to setup error logging and output.

Notes

Upgrading to 4.4

Situation: You want to upgrade from version 4.2 or 4.3 to 4.4.

In short

  1. Change all global extensions to local ones (see "Common procedures" above).
  2. Install new source code (see "Common procedures" above).
  3. Upgrade database (see "Common procedures" above).

Important: Modify .htaccess

Use the Update Wizard "checkForCompressionLevel", if you have [BE][compressionLevel] set.

If so, you must add the following to .htaccess in the TYPO3 root folder: 

# Allow Apache to handle compressed .js and .css files correctly
<FilesMatch "\.js\.gzip$">
  AddType "text/javascript" .gzip
</FilesMatch>
<FilesMatch "\.css\.gzip$">
  AddType "text/css" .gzip
</FilesMatch>
AddEncoding gzip .gzip

Next steps

  • Then use the section "Database Analyser", do a "Compare" and do the proposed updates until the Install Tool says, that everything is OK.
  • Then go to the section "Edit files in typo3conf/" and delete the temp_CACHED*-files. This clears all caches.

After upgrading

  • If you used a skin, which is not yet compatible with TYPO3 4.4, you must uninstall it and install t3skin instead. You can do that in the Install Tool, All Configuration by modifying the value for [EXT][extList]: Remove your old skin and add t3skin instead. Afterwards you have to delete the temp_CACHED*-files again.
  • Upgrade the extensions you use. Delete unused extensions.
  • Go to the Extension Manager and open the section "Translation Handling". Check and update your translations. In TYPO3 4.4 all modules are translatable. Since TYPO3 4.3 new texts have been added. (The translations are available, after the translation team for your language has translated the texts.)
  • Here is an error document which explains, how to setup error logging and output.

Notes

  • If you see a completely unstyled backend after doing the upgrade, check the source code for included stylesheets like ../typo3temp/compressor/ext-all-notheme-ce48a38ef3fa7a8a196ad140c5ee728d.css.gzip?1275419916.
    If you find .gzip files included, you have [BE][compressionLevel] set. Make sure that you have added the needed lines to .htaccess as described above. Then clear your browser cache and try again.
    If that still does not help, your server does not support gzipped files. To work around that problem, go to the Install Tool and set [BE][compressionLevel] = 0.
  • If the backend is still very badly styled (many icons are missing and the install tool looks ugly), check the web server's error log file. If it tells you that some directives in .htaccess are not allowed, check the main (or, depending on your installation, the vHost's) Apache configuration for AllowOverride. As TYPO3 uses mod_expire since version 4.3, it is necessary to allow the settings made by TYPO3 in .htaccess. The easiest change is to set AllowOverride All.
  • If the backend is still somehow unstyled, carefully check the UNIX user/group of the files of your TYPO3 installation once again. If they are not the same as the user who accesses the files, it will as well show the same unstyled result for the backend and the login page. The install tool will not even start. If you find a mismatch, use chown to set the correct user/group: 
    $ chown -R [user].[group] /var/www/path/to/your/files
  • ...

Upgrading to 4.5 Long Term Support

Situation: You want to upgrade from version 4.4 to 4.5 with Long Term Support.

In short

  1. Change all global extensions to local ones (see "Common procedures" above).
  2. Install new source code (see "Common procedures" above).
  3. Upgrade database (see "Common procedures" above). Also 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 the Update Wizard. See 18501: Core - Enable UTF-8 by default [Closed to Michael Stucki] for details.

You can find upgrading instructions in our page about Updating to UTF-8.

Next steps

  • Then use the section "Database Analyser", do a "Compare" and do the proposed updates until the Install Tool says, that everything is OK.
  • Below "Compare", you find "Dump static data" and the link "IMPORT". Follow this link and select table "sys_ter" in order to add initial "TYPO3.org Main Repository" to the list of repositories.
  • Then go to the section "Edit files in typo3conf/" and delete the temp_CACHED*-files. This clears all caches.

After upgrading

  • Upgrade the extensions you use. Delete unused extensions.
  • Go to the Extension Manager and open the section "Translation Handling". Check and update your translations. In TYPO3 4.5 especially the texts in the forms for editing Pages and Content Elements have been changed. If you don't update your translations, you will partly see these texts in English only. (The translations are available, after the translation team for your language has translated the texts.)

Notes

  • 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.
  • ...

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!

In short

  1. Change all global extensions to local ones (see "Common procedures" above).
  2. Install new source code (see "Common procedures" above).
  3. Upgrade database (see "Common procedures" above).

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).

After upgrading

  • Upgrade the extensions you use. Delete unused extensions.
  • In the Extension Manager, section "Translation Handling", check and update your 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.

Notes

  • 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.
  • ...
Retrieved from "http://wiki.typo3.org/wiki/index.php?title=Upgrade&oldid=59410"
Personal tools
Namespaces
Variants
Actions