Installation and Upgrade Guide

Previous Key:doc_guide_install
Version:master (9-dev)
Description:This document describes the file structure of TYPO3 and takes you step by step through the installation. It does not focus on specific operating systems, but contains some hints on general TYPO3 installation issues with regards to Apache, PHP and MySQL.
Keywords:forAdmins, forBeginners
Author:Documentation Team
License:Open Publication License available from
Rendered:2019-03-12 15:38

The content of this document is related to TYPO3,

a GNU/GPL CMS/Framework available from

Official documentation

This document is included as part of the official TYPO3 documentation. It has been approved by the TYPO3 Documentation Team following a peer review process. The reader should expect the information in this document to be accurate; please report discrepancies to the Documentation Team ( Official documents are kept up-to-date to the best of the Documentation Team's abilities.


This document is a Guide. Guides are designed to familiarize a reader with a specific topic in order to provide a working knowledge of that particular process. Readers should peruse the guide from cover to cover in order to gain a practical overview of the process. Once completed, the Guide becomes a practical reference tool to which a reader can refer as needed. Guides offer advice on how best to achieve a given task.




About this Document

This manual provides instructions on how to install and also upgrade an existing TYPO3 CMS installation.

The "Installation" section is aimed at beginners who want to set up a new installation of TYPO3 CMS. The "Update" section targets those who already have a running website and wish to upgrade it to a newer version of TYPO3 CMS.

It is recommended that you follow each of the steps in the "Quick Installation" section in order to ensure that your installation is completed correctly. After this point you may wish to take a closer a look at the "In-Depth Installation" section to find out how to further configure and customize your installation of TYPO3.

What's New

Updated the manual for TYPO3 CMS version 8.7.


This manual was originally written by Kasper Skårhøj and is now kept up to date by the documentation team.


For general questions about the documentation get in touch by writing to .

If you find a bug in this manual, please be so kind as to check the online version on From there you can hit the "Edit me on GitHub" button in the top right corner and submit a pull request via GitHub. Alternatively you can just file an issue using the bug tracker:

Maintaining high quality documentation requires time and effort and the TYPO3 Documentation Team always appreciates support. If you want to support us, please join the documentation mailing list/forum ( or the slack channel #typo3-documentation.

Quick Installation

For those already familiar with running web software, get started quickly with this quick install guide. For a more detailed description, take a look at the section In-Depth Installation.

The following instructions assume you are able to create symlinks on the target machine (which needs elevated permissions on Windows machines).


  • Running web server (Apache, Nginx, IIS...)
  • PHP ≥ 7.2 installed

Install TYPO3 via composer


The recommended way of installing TYPO3 is via Composer, as described on this page.

To create a new TYPO3 project use the TYPO3 Base Distribution:

# Download the Base Distribution, the latest "stable" release (9.5)
composer create-project typo3/cms-base-distribution YourNewProjectFolder


To install TYPO3 via the composer command on windows, it should be started as admin or explicitly given the right to create symlinks (use for example a powershell or git bash started with admin rights).

After composer create project ... executed, you should have the following folder structure:

Folder Structure

The folder structure after composer installation.

Point the document root of your web server to the public folder.

If you do not want to use Composer, follow the package installation guide.

Next Steps

Continue with The Install Tool.

Get and Unpack the TYPO3 Package


The recommended way of installing TYPO3 is via Composer. This page describes an alternative method of installing TYPO3 without Composer.

Installing on a Unix Server

  1. Get the Source Package from and upload this package to your web server. Put it one level above the document root. In this example, we will use the .tar.gz file format. (If you are not sure which package you should choose, read the section "Which Package and Which Format?" in the in-depth part of the manual). Use the shell to execute the following commands:

    /var/www/site/htdocs/$ cd ..
    /var/www/site/$ wget -O typo3_src-9.5.x.tar.gz
  2. Unpack the typo3_src-9.5.x.tar.gz file on your web server:

    /var/www/site/$ tar xzf typo3_src-9.5.x.tar.gz


    Be aware that the x in the extracted folder will be replaced with the latest bugfix version, e.g. typo3_src-9.5.1.


    You can also unpack the package on your local PC and then upload the unpacked contents onto your web server. However, the package contains several thousand files which will then need to uploaded one at a time. This process is time intensive and not recommended.

  3. Create these symlinks in your document root:

    cd htdocs
    ln -s ../typo3_src-9.5.x typo3_src
    ln -s typo3_src/index.php index.php
    ln -s typo3_src/typo3 typo3

You end up with the following structure of files:

htdocs/typo3_src -> ../typo3_src-9.5.x/
htdocs/typo3 -> typo3_src/typo3/
htdocs/index.php -> typo3_src/index.php

The advantage of this setup is that all files from the TYPO3 Source package are kept together in the typo3_src-9.5.x folder and separated from other files of your installation. This allows you to easily replace this folder when a new patchlevel version of TYPO3 is released.


This setup allows the administrator to use the "Core Updater" feature in the Admin Tool / Maintenance area to update the TYPO3 installation.

Installing on a Windows Server

  1. Get the Source Package from and extract it on your local PC. Use FTP, SFTP or similar to upload the contents of this package to your web server. Put them one level above the document root. For this manual, we will use the .zip file. (If you are not sure which package you should choose, read the section "Which Package and Which Format?" in the in-depth part of the manual).

  2. Use the shell to create these symbolic links in your document root:

    cd htdocs
    mklink /d typo3_src ..\typo3_src-9.5.x
    mklink /d typo3 typo3_src\typo3
    mklink index.php typo3_src\index.php

    You end up with the following structure of files:

    htdocs/typo3_src -> ../typo3_src-9.5.x/
    htdocs/typo3 -> typo3_src/typo3/
    htdocs/index.php -> typo3_src/index.php

After extraction and symlink creation continue with the steps in The Install Tool

The Install Tool

  1. Hit the start page of your freshly created site with your browser and you should see the "thank you for downloading"-message.

    Success message after download.

    Success message after download.

  2. Create the file FIRST_INSTALL in your web root directory (public folder) and reload the page. You will be redirected to the install tool. It will guide you through the steps for installing TYPO3. The Install Tool is located in 'typo3/install' in your installation which for example would be

  3. This is what you should see:

    first step

    Install Tool in 1-2-3 mode, first step.

  4. In case you have problems in your Environment, you will get warnings or hints in this screen. In this case, you should try to fix them; the "Troubleshooting" section might help you.

  5. Choose database connection. In this step, you can choose the database management system TYPO3 should run with. Via the GUI you can choose between MySQL (compatible to MariaDB), PostGres or SQLite if available. SQLite requires no further configuration and is a good choice for testing TYPO3, but you should choose one of the others for running production grade web sites.

    third step

    Install Tool in 1-2-3 mode, second step.

  6. Choose Database. If you did not select SQLite in the previous step, you have to select an empty database for TYPO3 now (or create one if your user is allowed to).

  7. Enter a username and password for your first TYPO3 administrator account. (For security reasons, it's best not to use the name admin.) This password will also be used for the Install Tool. The "site name" will identify this installation (in the page tree and browser title).

    forth step

    Install Tool in 1-2-3 mode, forth step.

  8. In the last step you can choose whether you want to start with an empty TYPO3 or if you want to have a basis to start from.

    fifth step

    Install Tool in 1-2-3 mode, fifth step.

  9. The basic installation is now complete!

After the basic installation procedure is complete, TYPO3 will be working and the most appropriate settings will have been made for you. You will get redirected to the Backend and can log in with your administrator account.

If you want to make changes to your installation settings at a later date, use the "Admin Tools" in the backend. You can find more information in the section "In-Depth Installation", subsection "TYPO3 System Management" below.

In-Depth Installation

System Requirements

TYPO3 requires a web server, PHP and a database system.

  • TYPO3 requires a web server which can run PHP (e.g. Apache, Nginx or IIS).
  • TYPO3 9 requires at least PHP 7.2.x
  • TYPO3 can be used with a great many database systems (e.g. MySQL or Postgres). If you use MySQL, you will need to install at least MySQL 5.5.

If you use an Apache web server, the module mod_rewrite must be activated. Certain PHP extensions are necessary, others recommended. You possibly want to adjust the memory limit; see below.

If you want TYPO3 to automatically carry out image processing – for example scaling or cropping – you will need GraphicsMagick (version 1.3 or newer) or ImageMagick (version 6 or newer) installed on the server. (GraphicsMagick should be prefered.)

For an overview see also

Should you encounter problems, the "Troubleshooting" section at the end of this document will help.

Database Environment

TYPO3 works with database management systems in the above mentioned versions. The InnoDB engine is required to be enabled in MySQL.

Required Database Privileges

The database user needs at least the following privileges on the TYPO3 database:


It is recommended to also grant the following privileges:


Web Server Environment

  • Make sure AllowOverride in the webserver configuration includes "Indexes" and "FileInfo" if you use Apache as webserver.
  • Enabled modules "mod_expires" and "mod_rewrite" (to enable human readable urls)
PHP Environment
  • memory_limit set to at least 256M recommended
  • max_execution_time set to at least 30 (240 seconds recommended)
  • max_input_vars set to at least 1500
PHP Required Extensions

Your PHP needs to support the following extensions. Install will check if these are available.

  • These are usually part of the standard PHP package on most distributions:
    • PDO
    • json
    • pcre >= 8.38
    • session
    • xml
    • filter
    • hash
    • mbstring
    • SPL
    • standard
  • These might have to be installed separately:
    • fileinfo
    • gd
    • zip
    • zlib
    • openssl
    • intl
    • mysqli (if you use MySQL, MariaDB as DBMS)
    • postgresql (if you use PostgreSQL as DBMS)
    • sqlsrv (if you use SQL Server as DBMS)
    • sqlite (if you use SQLite as DBMS)

Which Package and Which Format?

The recommended way of installing TYPO3 is via the PHP package manager Composer. For detailed instructions on how to install TYPO3 using Composer, visit the Install TYPO3 via composer section of this manual.

If you do not have access to Composer, you can install TYPO3 by downloading and then extracting its source package on your web server. TYPO3's source package can be found here:

Which File Format to Use

The TYPO3 Source package is available as a .zip or .tar.gz distribution. Their content is the same and you should download the one that you will be able to extract directly on your web server (Windows based systems are more likely to use the .zip file while Linux distributions tend to use the .tar.gz file).

The Package in Detail

TYPO3 Folders and Files on Root Level

The following files and folders are part of the TYPO3 package in a Composer based installation.

is the document root and public entry point.
contains system files, like caches, logs, sessions...
the Composer vendor directory contains third-party packages, libraries etc.
The 'public' Folder

The following files and folders will be created in the public folder during the installation of TYPO3:

contains your site assets and files, local to the website. You can e.g. put images, user uploads and other assets here. By default this folder is used to store files, which have been uploaded in the TYPO3 Backend (fileadmin/ is configured as the first default storage). fileadmin/ must be writable for the web server user. Files in fileadmin/ are for editors, you should not put any site configuration files here. Exclude the fileadmin/ folder from your version control to make sure not to mix development files and user files.
contains configuration and extensions for the local site.
will hold the local extensions available for this installation, extensions can be required via Composer.
is the main configuration file of your installation and the one the customized values of all the Install Tool options get written to. It has to be writable and will be updated automatically by the Maintenance Tools and the Extension Manager. You can edit this file manually, but make sure you keep the PHP syntax working.
contains information about the extensions, which are activated in your system.
is an additional configuration file, which is executed on every request after the LocalConfiguration.php has been loaded. It can be used to manipulate the configuration of $GLOBALS['TYPO3_CONF_VARS']. This file is not created automatically; create it if you need it.
the main script for the website Frontend
The var Folder
is where file based caches will be stored.
contains charset conversion tables.
contains language labels for a translated TYPO3 backend. You can download more languages via "Maintenance" > "Manage language labels"
is where file based locks are created.
the default location for TYPO3 log files. Can be configured via the TYPO3 logging framework. See Logging Framework <>.
is where sessions are stored.
acts as transient storage during file operations for example.

Custom Folders?

Yes, just add whatever you like. Why not?

TYPO3 System Management

The TYPO3 Admin Tool area provides tools to help with the maintenance of your installation: Upgrading, checking the system environment, configuring settings from and solving problems. The standalone tool usage is not dependent on a working Backend, and you access it using a single password.

First go to your site and enter the admin tool (


If you see a message "The Install Tool is locked", create a new file named "ENABLE_INSTALL_TOOL" in the folder public/typo3conf/. Then reload the page.


The Admin tool was called "Install Tool" in earlier versions, you will likely still see that term in some places.


The section provides basic information about your system and several functions which you need for maintenance tasks.

Admin Tools: Maintenance Overview

The "Maintenance" section of the Install Tool.

The Flush TYPO3 and PHP Cache functionality can empty all caches: Frontend, Backend, language caches and the OPCode Cache.

With Analyze Database Structure you can compare the current structure of your database with the expected structure for the TYPO3 version you are using. The next step allows you to update the structure of your database accordingly.

Remove Temporary Assets allows you to clear temporary files and will trigger regeneration when they are needed next.

Rebuild PHP Autoload Information resets autoload information for all active third party extensions.

With Clear persistent database tables you can cleanup non-caching tables like the history, log or backend sessions. Be aware that clearing backend sessions will log out all active users. Clearing the history will remove all history entries, you will not be able to use the content element history to undo changes anymore.

"Create administrative user" allows to create a new administrator (if wanted with system maintenance role on top). The system maintainer role adds the maintenance tools to the menu and allows easy access to the standalone admin tool.

If for some reason you or your editors have problems when editing in the TYPO3 backend, clearing the backend user settings might help. In those preferences various settings of a backend editor are stored, for example: which page tree nodes are currently expanded. Click on "Reset backend user preferences" to clear these settings and set them to their defaults.


Some technical background: User settings get saved in the database table be_users in the uc (=User Configuration) field. When resetting the backend user preferences this field is set to an empty string.

Install new TYPO3 backend languages with the Manage language packs functionality. You can update existing language packs (for example after installing new extensions) or add new languages to the system. Afterwards, you can choose between all installed languages in your user settings.


This area allows you to configure both TYPO3 extensions as well as the core.

In Extension Configuration you can configure all enabled extensions that provide custom configuration options.

Via Change Install Tool Password you can set a new password for the maintenance area.

With Manage system maintainers you can add new system maintainers (admin users with the additional role of system maintainers). System maintainers have easier access to the maintenance tools of TYPO3. Be aware that this is mainly a usability enhancement, blinding maintenance options for normal administrators. As administrators still have elevated permissions you should still be careful which users can be trusted with these rights.

At Configuration Presets TYPO3 offers presets for common settings groups. It allows for easier configuration of settings for debugging, image handling, mail configuration and password hashing.

TYPO3 provides Feature Toggles for certain features that have a major impact on your system. You can enable or disable these features here.


On new installation it is recommended to activate the following features for TYPO3 9 LTS:

  • unifiedPageTranslationHandling
  • TypoScript.strictSyntax
  • simplifiedControllerActionDispatching

Configure Installation-Wide Options (previously known as "All Configuration") allows you to configure settings that impact how your complete TYPO3 installation behaves.


If you are new to TYPO3, take some time to read through all the options and their explanation to get an impression of what TYPO3 offers.

The Check for broken extensions can be run to make sure that all ext_tables and ext_localconf files contain valid PHP code, so that they can be loaded without breaking the system.

The TCA Migrations can be used to check whether the current TCA needs migrations and displays applied migrations.

The Core update can update the TYPO3 Core to the newest minor version.

Apart from these functions, this section also contains options to change the install tool password, to change the site name, to change the encryption key and to create a Backend administrator user. Usually you do not need these functions.


You don't need the upgrade section while installing TYPO3. These functions will be explained in a later chapter about upgrading TYPO3. See Upgrade.


The section contains a huge number of environment checks, which notify you of (potential) problems in your installation.

The Environment Overview provides a short system overview that you can also access via Application Information in the top bar.

The Environment Status runs checks on your server environment and reports potentially wrong or missing settings.

With Directory Status you can check whether all required files and folders exist and are writable when necessary. It also shows the default file and folder permissions TYPO3 will apply on creation of assets.

PHP Info simply outputs the phpinfo().

Test Mail Setup allows you to test the mail setup of TYPO3 by sending a test mail.


If the test mail does not arrive, check the settings via "Settings" > "Configuration Presets" > "Mail".

Image Processing checks various image rendering capabilities of your system and displays hints if something goes wrong.


If rendering fails you can copy the executed command and see if it works on your favorite command line. If that works, the tool itself is working but TYPO3 might have problems executing it. If the command does not work, you might need to adjust the settings (via "Settings" > "Configuration Presets" > "Image Handling").

The Distributions

Distributions were created to give new users easy access to a preconfigured installation of TYPO3 that they could then use without the need to set up and configure various parts of the CMS such as page structure, content and templating.

When installing TYPO3 for the first time, you will be given the option to access a set of "Preconfigured Distributions" once the installation is complete. Upon selecting this option, you will be redirected to your installations "Extension Manger" and given a list of Distributions to choose from.

For an existing installation of TYPO3, distributions are already available and can be accessed in the Extension Manager.


If you installed TYPO3 via Composer, all extensions and distributions will need to be installed and managed via Composer.

Introduction Package

The Introduction Package is a complete, fully operational website. It it based on a responsive design using bootstrap templates and contains example content for testing and evaluation. This is ideal for new users who wish to have a "look around" and get more familiar with the CMS.

Introduction Package

The Introduction Package provides a fully operational website based on bootstrap.

Installing Distributions Without Composer

For testing and evaluation we recommend that you use the Introduction Package, but several other distributions are available.

Move to the ADMIN TOOLS > Extensions module and choose "Get preconfigured distribution" from the menu in the docheader. Select the Distribution you would like to use and select the "Install" button.

If you want to build your web site from scratch, just go ahead without using a Distribution. You can then start with a completely empty installation of TYPO3.

Installing Distributions With Composer

To install the Introduction Package or any other distribution on a Composer based installation use composer require typo3/cms-introduction (change the package name to the distribution you want). Afterwards use the following commands to activate the extension(s) via command line:

./vendor/bin/typo3 extension:activate bootstrap_package
./vendor/bin/typo3 extension:activate introduction

In this case, the Introduction Package depends on the bootstrap_package, so both packages have to be installed.

Move to the ADMIN TOOLS > Extensions module and choose "Get preconfigured distribution" from the menu in the docheader. Just choose the Distribution you would like to use and hit the "Install" button.

Translating the Backend

In order to use translations in the TYPO3 Backend, you first need to download the translations and then select them for the Backend users.

Download Translations for the Backend

Log in to the Backend and go to the Backend module "Maintenance".

In the section "Manage Language Packs" click "Manage Languages". In the modal window click "Add Language" to add a new language to TYPO3.

After that click "Update all" to update the translations. This may take some time. Some extensions do not have translatable texts and so also do not have translations available. If for an extension you get an error message, wait until the update has finished and then press "Update from repository" again.


After installing new extensions, you'll have to update the language packs again to get translations for the newly installed packages.

Change the Language for a Backend User

The Backend can be displayed in different languages for different users. Go to the module "User settings". On the tab "Personal data" you can choose between the languages, which you downloaded in the last step. Select the language, which you want to use. Then click "Save Configuration" and after that reload the Backend.

When you are logged in as an administrator, you can also modify user settings of other users: Go to the module "Backend Users" and switch to the Backend user, which you want to edit. After that you can set user settings for this user and adjust his/her language as well.


When a new version of TYPO3 is released, you should follow the guideline in this chapter in order to do an upgrade. Also follow any additional upgrade information carefully. You might e.g. want to skim the ChangeLog to see if any features affect the way your site works.


Version specific upgrade notes

While this guide is the general guideline to follow for a TYPO3 Upgrade, some version specific information are additionally available in the TYPO3 Wiki. Use them as an amendment to this guide!


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!

Basically these are the steps to be done to update your TYPO3 site:


Before you start

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

  • Enable the deprecation log and let it run for a while while the website is used to catch all deprecations
  • Check installed extensions for versions compatible to the target TYPO3 version
  • Try the upgrade on a development system first or create a parallel instance
  • Run the extension scanner (see below)

Handling 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 (Backend > Module "Upgrade" > "Scan Extension Files") or as a standalone tool (

Read where to find deprecation documentation in the chapter about Check the ChangeLog.


TYPO3 aims at providing a reliable backwards compatibility between versions:

  • Minor versions are always backwards compatible
  • Major versions may contain breaking changes - normally these are deprecated in the version before
  • 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).


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.

Reference Index

Without command line

Still in your old TYPO3 version, go to the "System" > "DB check" module and use the "Check and update global 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.

Install the new Source


The recommended installation of TYPO3 is based on composer.

Upgrading a composer based system


TYPO3 v9 LTS has no support for the package typo3/cms anymore - instead all TYPO3 system extensions are now single packages. When upgrading, remove the typo3/cms package and require the single packages you need. To make selecting the packages easier, you can use to find the packages you need.

Use composer to update your system via for example composer require typo3/cms-backend:^9.5 typo3/cms-core:^9.5 typo3/cms-extbase:^9.5 typo3/cms-extensionmanager:^9.5 typo3/cms-filelist:^9.5 typo3/cms-fluid:^9.5 typo3/cms-frontend:^9.5 typo3/cms-install:^9.5 typo3/cms-recordlist:^9.5 --update-with-dependencies

If you have extensions installed, you will have to find the corresponding newer versions you want to install for your new major version and update them, too.


composer require typo3/cms-backend:^9.5 typo3/cms-core:^9.5 \
   typo3/cms-extbase:^9.5 typo3/cms-extensionmanager:^9.5 \
   typo3/cms-filelist:^9.5 typo3/cms-fluid:^9.5 typo3/cms-frontend:^9.5 \
   typo3/cms-install:^9.5 typo3/cms-recordlist:^9.5 georgringer/news:^7.0 \

To find the matching extension versions you can go to, search for your extension and take a look at the requires section.

extension on packagist

The "News" extension on packagist

Using the Core Updater

The Install Tool in the section "Important Actions" provides a function to update the TYPO3 Core.

In the section "Important Actions" scroll down to "Core update" and click the "Check for core updates" button. If the requirements are met, TYPO3 will automatically install the new source code.


For the Core Updater to work, the following setup is required:

  • It only works under Unix and MacOS.
  • typo3_src must be a symlink.
  • This symlink needs to be writable (and deletable) by the web server user.
  • document root needs to be writable.
  • One path above document root (../) needs to be writable (new directories need to be allowed to be created).
  • The tar command must be available for extracting the Source package.


Disabling the Core Updater

The Core Updater functionality can be disabled (in order to avoid users using it, i.e. if you use your own update mechanism). To disable the core updater, you can set this environment variable:


For example in Apache:


or for nginx:

server {
  location ~ path/to/it {
    include fastcgi_params;
    fastcgi_param TYPO3_DISABLE_CORE_UPDATER "1";

This will disable the button and all related functionality in the Install Tool.

Installing the source manually

Go to and download the Source package of the new TYPO3 version.

Extract the package on your web server and - in your TYPO3 document root - adjust the typo3_src symlink.

What's the next step?

In case you did a minor update, e.g. from TYPO3 9.5.0 to 9.5.1, database updates are usually not necessary. All you still have to do is to remove the temporary cache files. After that your update is finished.


Make sure to read the release notes even of minor versions carefully. While we take great care to keep the minor updates as easy as possible especially when releasing security updates more steps might be necessary.

In case of a major update, e.g. from TYPO3 8.7 to 9.5, go ahead with the next step!

Also check out the breaking changes listed in Changelog for the new version.

Convert global Extensions

If you use global extensions, 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 Extension Manager.
  • Uninstall the global extension.
  • Delete the files of the extension from typo3/ext/, including the directory of that extension itself.
  • Reinstall the extension from TER, 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

Use the upgrade wizard

Enter the Install Tool at on your TYPO3 site.

Upgrade wizard

The Upgrade Wizard in the Install Tool.

TYPO3 provides an upgrade wizard for easy upgrading. Go to the "Upgrade Wizard" section and take a look at the different wizards provided. You should go them through one by one.

You must start by using the "Update database schema: Create tables and fields" wizard if it's displayed, which adds new tables and columns to the database.

Click "Execute". Now all ext_tables.sql files from core and extensions are read and compared to your current database tables and columns. Any missing tables and columns will be shown and you'll be able to execute queries sufficient to add them.

After you added these tables and columns, go on to the next wizard.


If you have CLI access you can run the update wizards on command line, too. This allows you to run all upgrade wizards at once and might help with long running wizards that may fail because of webserver timeouts otherwise

Run ./vendor/bin/typo3 upgrade:list -a to show a complete status of upgrade wizards.

Use ./vendor/bin/typo3 upgrade:run <wizardName> to run a specific wizard.

Use ./vendor/bin/typo3 upgrade:run to run all wizards.

The "Version Compatibility" wizard sets the compatibility version of your TYPO3 installation to the new version. This allows your Frontend output to use new features of the new TYPO3 version.


This wizard might affect how your website is rendered. After finishing the upgrade, check that your website still displays the way it is supposed to be and adjust your TypoScript if necessary.

Go through all wizards and apply the (database) updates they propose. Please note that some wizards provide optional features, like installing system extensions (for example simulatestatic) that you may not need in your current installation, so take care to only apply those wizards, which you really need.

After running through the upgrade wizards go again to the Database Analyzer. You will be able to execute queries to adapt them so that the tables and columns used by the TYPO3 Core correspond to the structure required for the new TYPO3 version.


If you don't know the current Install Tool password, you can set a new one by entering one in the Install Tool login screen, hitting enter and then setting the displayed hash as value of ['BE']['installToolPassword'] in typo3conf/LocalConfiguration.php.

Run the Database Analyzer

While in the previous step, tables and columns have been changed or added to allow running the upgrade wizards smoothly. The next step gives you the possibility to remove old and unneeded tables and columns from the database.

Use the "Maintenance section" and click "Analyze Database".

The Database Analyzer before analyzing the database.

You will be able to execute queries to remove these tables and columns so that your database corresponds to the structure required for the new TYPO3 version.


Be careful if you have deliberately added columns and/or tables to your TYPO3 database for your own purposes! Those tables and columns are removed only if you mark them to be deleted of course, but please be careful that you don't delete them by mistake!


TYPO3 does not directly remove tables and fields, but first renames them with a prefix zzz_deleted_*. This allows checking whether the fields and tables really are not needed anymore or were accidentally marked as deleted by wrong configuration.

When you are sure you aren't going to need them anymore, you can drop them via the wizard.

Select the upgrades you want and press "Execute":

Database analyzer

The Database Analyzer

When you then click "Compare current database with specification" again and you only see the message

Database analyzer

The Database Analyzer with no updates to do.

then all database updates have been applied.

Clear User Settings

You might consider clearing the Backend user preferences. This can avoid problems, if something in the upgrade requires this. Go to "Clean up", scroll to "Reset user preferences" and click "Reset backend user preferences".

Reset User Preferences

Reset user preferences in install tool.

Clear Caches

You should also clear all caches when upgrading.

Go to "Maintenance" and click "Flush":

Flush Caches

The option "Flush" in the Install Tool.

Additionally, after an upgrade to a new major version, you should also delete the other temporary files, which TYPO3 saves in typo3temp/. In the Install Tool go to "Clean up" to do so.

Remove temporary assets.

The option "Remove temporary assets" in the Install Tool.

Check the ChangeLog

Look through the ChangeLog online 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.

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

You can also find the ChangeLog in the Install Tool at "Upgrade Analysis". Here you can mark files as read after checking them, so you get a ToDo list for the upgrade.

Uprade Analysis

The "Uprade Analysis" in the Install Tool

Update Extensions (only on non-composer installations)

In the Backend, go to the extension manager and update the extensions you use. TYPO3 CMS stores a reference list of available extensions locally, so make sure that the list is up-to-date by clicking the "Update now" button in the "Get extensions" view.

You can also take this opportunity to delete all unused extensions, thereby making sure that there are no potential security "holes" in files stored on your server.

Update Translations

In the Install tool, go to the module "Maintenance" -> "Manage languages" and update your translations. If you don't update your translations, new texts will only be displayed in English. The translations are available, once the Translation Team for your language has translated the texts.

Manage language packs

The option "Manage language packs" in the Install Tool.

Migrate TYPO3 Project to Composer

Contributed initially by Albrecht Köhnlein July, 2018.


TYPO3 version

TYPO3 composer packages on can be found down to version 6.2.0: typo3/cms


Of course, you need Composer. It's a program, written in PHP. Instructions how to download and install Ccomposer can be found on

Folder structure

If your project root folder is identical to your web root folder, you must change that. Composer will add a vendor folder to your project root and if your project root and your web root are identical, this can be a security issue, because files in the vendor could be accessible directly via HTTP request.



You need a web root folder inside your project. You can find many tutorials with different names for your web root folder. The truth is: the name does not matter, because we can configure it in the settings in a later step. I will use public in my example.



If you do not have such a web root directory, you must refactor your project before continuing. Please be aware to tell your web server about the changed web root folder, if necessary.

Code Integrity

Your project must have the TYPO3 core and all installed extensions in original state. If you applied manual changes to the files, these will be lost during the migration steps.


If you need to apply hotfixes or patches to the TYPO3 core or publicly available extensions, this tutorial about applying patches via Composer could help, but requires some advanced steps.

Migration Steps

Delete Files

Yes, that's true. You have to delete some files, because they will be created by Composer in some of the next steps.

You have to delete, public/index.php, public/typo3/ and all the extensions inside public/typo3conf/ext/, you downloaded from TER or any other resources like GitHub. You even have to delete your own extensions, if they are available in a separate Git repository and, for example, included as Git submodule.

Please keep only your sitepackage extension or any other extension, which was explicitly built for your current project and does not have an own Git repository.

Configure Composer

Create a file with name composer.json in your project root, not inside your web root. At the moment, only these few lines are required:

    "repositories": [
            "type": "composer",
            "url": ""
    "extra": {
        "typo3/cms": {
            "cms-package-dir": "{$vendor-dir}/typo3/cms",
            "web-dir": "public"

You must set the correct name of your web root folder in property web-dir.

Add All Required Packages to Your Project

You can add all your required packages with the Composer command composer require. The full syntax is:

composer require anyvendorname/anypackagename:version


composer require typo3/cms:~7.6.0

There are different ways to define the version of the package, you want to install. The most common syntaxes start with ^ (e.g. ^7.6) or with ~ (e.g. ~7.6.0). A full documentation can be found at

In short:

  • ^7.6 or ^7.6.0 tells composer to add newest package of version 7.* with at least 7.6.0, but not version 8.
  • ~7.6.0 tells composer to add the newest package of version 7.6.* with at least 7.6.0, but not version 7.7.

You have to decide by yourself, which syntax fits best to your needs.

Install the Core
The Old Way: Add Everything

As already written above, the line to install TYPO3 7 LTS would be:

composer require typo3/cms:~7.6.0

While installing TYPO3 8 LTS works with this line:

composer require typo3/cms:~8.7.0
The New Way: Add Only Code, You Need

Since TYPO3 8.7.10 you can use a concept, called "subtree split". It will be mandatory for TYPO3 9. The concept means, you will not copy the full TYPO3 core package, including all system extensions, you will never use. But only install what you really want. You will not be able to install typo3/cms:^9, but have to name each system extension:

composer require typo3/cms-core:~9.0.0
composer require typo3/cms-backend:~9.0.0
composer require typo3/cms-frontend:~9.0.0
composer require ...

Or in one line:

composer require typo3/cms-core:~9.0.0 typo3/cms-backend:~9.0.0 typo3/cms-frontend:~9.0.0 ...

To find the correct package names, you can either take a look in the composer.json of any system extension or follow the naming convention typo3/cms-<extension name with dash "-" instead of underscore "_">, e.g. typo3/cms-fluid-styled-content.

Install Extensions from Packagist

You already know the TER and always used it to install extensions? Fine. But with Composer, the preferred way is to install extensions directly from This works great, when the maintainer uploaded them to there. Many well known extensions are already available. You only need to known the package name. There are multiple ways to find it:

Notice on Extension's TER Page

Extension maintainers optionally can link their TYPO3 extension in TER with the correct Composer key on Some maintainers already did that and if you search the extension in TER, you will see a message, which command and Composer key you can use to install this extension.

TER composer command


The command composer req is short for composer require. Both commands exactly do the same and are interchangeable.

Check in TER Satis

If you search the extension in and it's linked to, they are marked as "abandoned" and you will see a message, which Composer key should be used to install this extension.

satis abandoned note

See Warning During composer require Command

If you still install one of the abandoned extensions via its typo3-ter package key, you will also see a warning during the composer require command.

composer abandoned note

Check Manually

This is the most exhausting way. But it will work, even if the extension maintainer does not provide additional information.

  1. Search and open the extension, you want to install, in TER.

  2. Click button "Take a look into the code".

    TER screen shot

  3. Open file composer.json.

    file list

  4. Search for line with property "name", it's value should be formatted like vendor/package.

    file content

  5. Check, if the package can be found on

    packagist screen shot

Example: To install the mask extension in version 4.1.*, type:

composer require mask/mask:~4.1.0
Install Extension from TER

If the extension is not available on packagist, the good news is: All TER extensions are available via Composer! That's, why we added as repository to our composer.json some lines above. There are little naming conventions:

  • Vendor name is typo3-ter.
  • Underscores _ are replaced by dash -.


The extension any_fancy_extension's auto generated Composer package name would be typo3-ter/any-fancy-extension. To add this extension in version 1.2.*, type:

composer require typo3-ter/any-fancy-extension:~1.2.0

You can browse all available extensions and versions via


If you do not include any packages this way, you can remove the repository block named from your composer.json to improve speed.

Install Extension from Version Control System (e.g. GitHub, Gitlab, ...)

In some cases, you will have to install a TYPO3 extension, which is not available on or in the TER. Examples could be:

  • non-public extension only used by your company.
  • you forked and modified an existing extension.

As first step, you have to define the repository in your composer.json's "repositories" section. In this example, you find the additional lines added to the composer.json from above:

    "repositories": [
            "type": "composer",
            "url": ""
            "type": "vcs",
            "url": ""
    "extra": {
        "typo3/cms": {
            "cms-package-dir": "{$vendor-dir}/typo3/cms",
            "web-dir": "public"

The Git repository must be a TYPO3 extension, with all the required files (e.g. ext_emconf.php) and must contain a valid composer.json itself. How this file should look in your extension, can be found on or this blog post from Helmut Hummel. Please note, that Git tags are used as version numbers.

If you fulfill these requirements, you can add your extension in the same way like the other examples:

composer require foo/bar:~1.0.0

Include Individual Extensions like Site Packages

It's not necessary to move your project's site package to a dedicated Git repository to re-include it in your project. You can keep the files in your main project (e.g. public/typo3conf/ext/my_sitepackage). There is only one thing to do; Because TYPO3's autoload feature works differently in Composer based installations, you have to register your PHP class names in Composer. This is very easy when you use PHP namespaces:

"autoload": {
    "psr-4": {
        "VendorName\\MySitepackage\\": "public/typo3conf/ext/my_sitepackage/Classes/",
        "VendorName\\AnyOtherExtension\\": "public/typo3conf/ext/any_other_extension/Classes/"

For extension without PHP namespaces, this section has to look a bit differently. You can decide by yourself, if you want to list each PHP file manually or if Composer should search for them inside a folder:

"autoload": {
    "classmap": [

To complete our example composer.json, it would look like this:

    "repositories": [
            "type": "composer",
            "url": ""
            "type": "vcs",
            "url": ""
    "extra": {
        "typo3/cms": {
            "cms-package-dir": "{$vendor-dir}/typo3/cms",
            "web-dir": "public"
    "autoload": {
        "psr-4": {
            "VendorName\\MySitepackage\\": "public/typo3conf/ext/my_sitepackage/Classes/",
            "VendorName\\AnyOtherExtension\\": "public/typo3conf/ext/any_other_extension/Classes/"
        "classmap": [


If you want to keep your typo3conf/ext directory empty and autoload information only in extensions' composer.json, but not in your project's composer.json, there is an alternative way to include your individual extensions in the chapter completely clear "typo3conf/ext" folder in the Best practices section.


Add to version control system

If you use a version control system like Git, it's important to add both files, the composer.json and composer.lock (which automatically was created during the previous steps).

On the other side, some files and folders, which are added by composer, should be excluded:

  • public/index.php
  • public/typo3/
  • vendor/
  • The extensions, you added via composer

A .gitignore file could look like this:

# allow some extensions

Checkout from version control system

All your co-workers should always run composer install after they checked out the files. This command will install the packages and versions, defined in composer.lock. So you and your co-workers always can be sure to have installed the same versions of the TYPO3 core and the extensions.

Best Practices

Run Composer Locally

You should not run composer on your live webspace. You should always run composer on your local or a dedicated deployment machine, so you can test if everything worked fine. After running your tests, you can deploy the vendor and public folder to your web server.

To avoid conflicts between your local and your server's PHP version, you can define your server's PHP version in your composer.json file (e.g. {"platform": {"php": "7.2"}}), so composer will always check the correct dependencies.

Update Packages

After updating any packages, you always should commit your composer.lock to your version control system and your co-workers should run composer install after checking out the updates.

Update all Packages

Run composer update without any other attributes, to update all packages. Composer will always try to install the newest packages that match the defined version constraints.


Be careful with that. This command may cause negative effects if you do not have proper version constraints in your composer.json. You always should prefer to update your packages separately.

Update Single Packages

When you want to update single packages, you can call composer update with the package name. You should always add --with-all-dependencies attribute to also update the required third party packages.

Update TYPO3 Core

Without "subtree split":

composer update typo3/cms --with-all-dependencies

With "subtree split":

composer update typo3/cms-* --with-all-dependencies
Update Extensions Like "news"
composer update georgringer/news --with-all-dependencies

Use Dev Requirements

Add packages with --dev attribute to add packages only to your local development environment. This is very useful for packages, you do not need or do not want to have on your live server, e.g. PHPUnit or Testing-Frameworks:

composer require typo3/testing-framework:^2.0 --dev

During your deployment routine, you should run composer install with attribute --no-dev. So the dev requirements are not installed.

composer install --no-dev

Remove Extensions

You can use the composer command remove to uninstall extensions or other composer packages.

composer remove georgringer/news

Don't forget to commit your updated composer.lock to your version control system.


Please be sure to disable extensions in TYPO3's Extension Manager, before removing them with composer. Or ensure to regenerate your typo3conf/PackageStates.php file automatically, after removing the packages. You could use the extension "typo3_console" for that

Check for Available Updates

Run composer outdated to see a list of available updates.

Completely Clear typo3conf/ext Folder

In the "Migration Steps" chapter, this tutorial explained, how you can keep your individual extension in "typo3conf/ext" and in the "Co-working" section, there was a part about how to add rules to your .gitignore file to exclude typo3conf/ext from, but keep your individual extensions in Git.

If you are searching for a solution to keep your typo3conf/ext folder clean and unify the extension handling even for your project's individual extension, this chapter might be useful.

Define a Local Path Repository

Create a directory packages in your project root folder and define this folder as a repository of type "path" in your composer.json:

    "repositories": [
            "type": "path",
            "url": "./packages/*"
Include Your Individual Extensions From packages Folder

In the next step, you move all your individual extensions from public/typo3conf/ext to packages. And for this way to include them, it's important, that each extension has it's own correct composer.json file. How this file should look in your extension, can be found on or this blog post from Helmut Hummel.

Assumed, your package key is, foo/bar, you can type the following command to include your extension to your project:

composer require foo/bar:@dev

In this case, it's the easiest way to not define any composer version number, but tell composer to use the latest dev state.


The autoload information now comes with the extension's composer.json and can be removed from your project's composer.json.

Exclude typo3conf/ext from Version Control System

To finish your cleanup of "typo3conf/ext", you should keep the line /public/typo3conf/ext/* in your .gitignore, but remove all lines, starting with !/public/typo3conf/ext/.

Useful Packages and Bundles

Simplify "Subtree Split" Installations

Instead of explicitly requiring each core extension, you can require typo3/minimal, which brings the minimal required set of system extensions.

TYPO3 CMS Base Distribution

Primarily, typo3/cms-base-distribution is not meant to be used with composer require, but to really quickly start new composer based TYPO3 projects.

Nevertheless, it's very good to have heard about it. If you're interested in more information, you should check the packages README.

Secure Web

helhum/typo3-secure-web follows the very interesting concept to split the traditional web root directory into two parts: the "public" one for all the resources, that must be directly accessible via HTTP (images, styles, etc.) - and the "private" folder, where all the PHP will be located.

This helps to make your TYPO3 installations even more secure!


The following sections contain hints to help you solve common problems. Note that you should also check the section "System Environment" in the Install Tool, in which TYPO3 will inform you about errors and warnings in your installation which might influence performance. Follow the advice given there to fix those issues. This helps to solve or prevent most issues.

During troubleshooting, in the "Configuration Presets" section of the Install Tool, under "Debug settings", you should select the "Debug" preset. This is especially helpful, if e.g. in the Frontend you only see a blank page. With debug settings activated, the PHP error message will be displayed, which will help you narrow down the problem.


Some settings may require adjustment for TYPO3 to operate correctly.

Enable necessary Modules

TYPO3 makes use of several Apache modules, two modules that will need to be enabled are mod_expires and mod_rewrite. Apache modules can be enabled by editing your http.conf file, locating the required module and removing the preceding hash symbol:

#LoadModule expires_module modules/
#LoadModule rewrite_module modules/

Adjust ThreadStackSize on Windows

If you are running TYPO3 on top of Windows, the extension manager might not appear. Instead you might only see a blank screen in the right frame.

This problem is caused by the value of ThreadStackSize, which on Windows systems by default is set too low. To fix this, add the following lines at the end of your httpd.conf file:

<IfModule mpm_winnt_module>
  ThreadStackSize 8388608


Install Tool

The "System Environment" section of the Install Tool provides detailed information about any missing PHP modules and any other settings that may not be configured correctly.

For example, the PHP extensions openssl and fileinfo must be enabled. This can be achieved by adding (or uncommenting) the following lines in the [PHP] section of your php.ini file:

On a Windows-based server, these are the extension files:


PHP Caches, Extension Classes etc.

There are some situations which can cause what appear to be totally illogical problems after an upgrade:

  • If extensions override classes in which functions have changed. Solution: Try disabling all extensions and then enable them one by one until the error recurs.
  • If a PHP cache somehow fails to re-cache scripts: in particular, if a change happened to a parent class overridden by a child class which was not updated. Solution: Remove ALL cached PHP files (for PHP-Accelerator, remove /tmp/phpa_*) and restart Apache.


Character Set

TYPO3 uses UTF-8 encoding, you will need to ensure that your instance of MySQL also uses UTF-8. When installing TYPO3 for the first time, you can select UTF-8 encoding when you create the database for the first time. For an existing database, you will have to set each table and column to use UTF-8.


Cached Files in typo3temp/

Generally you should know that TYPO3 generates temporary "cached" files and PHP scripts in typo3temp/Cache/. You can remove the whole typo3temp/Cache directory at any time; the directory structure and all the caches will be re-written on the next hit to the system.

A shortcut to remove these caches can be found in the Install Tool, under "Important Actions". This might be useful in the event your cache files become damaged and your system is not running correctly. The Install Tool won't load any of these caches or any extension, so it should be safe to use regardless of the corrupt state of the Caches.

Amongst other caches, under typo3temp/Cache/Code/cache_core/ you find files like these:

-rw-rw----   1 www-data   www-data   61555  2014-03-26 16:28   ext_localconf_8b0519db6112697cceedb50296df89b0ce04ff70.php
-rw-rw----   1 www-data   www-data   81995  2014-03-26 16:28   ext_tables_c3638687920118a92ab652cbf23a9ca69d4a6469.php

These files simply contain all ext_tables.php and ext_localconf.php files of the installed extensions concatenated in the order they are loaded. Therefore including one of these files would be the same as including potentially hundreds of PHP files and should improve performance.

Concerning these files you have to consider the following:

  1. Making changes to these files does not make sense, because they can be removed and recreated from the "originals" at any time. You should instead change the "originals".
  2. If you make changes to the original ext_tables.php or ext_localconf.php files in your extensions, you will have to clear the cached files away for your changes to take effect.

Possible Problems with the cached Files

Changing the absolute path to TYPO3

If you change the path of the TYPO3 installation, you might get a lot of errors like "Failed opening ..." or "Unable to access ...". The problem is that absolute file paths are hard-coded inside the cached files.

Fix: Clean the cache using the Install Tool: Go to "Important Actions" and use the "Clear all caches" function. Then hit the page again.

Changing Image processing Settings

When you change the settings for Image Processing (in normal mode), you must take into account that old images may still be in the typo3temp/ folder and that they prevent new files from being generated! This is especially important to know, if you are trying to set up image processing for the very first time.

The problem is solved by clearing the files in the typo3temp/ folder. Also make sure to clear the database table "cache_pages".


Only in the html version of this manual.

Targets for Cross-Referencing


Summary: 65 targets (65 with link text, 0 without).