The main configuration is achieved via a set of global settings stored in a global array called $GLOBALS['TYPO3_CONF_VARS'].

This chapter describes this global configuration in more details and gives hints to further configuration possibilities.

File config/system/settings.php

The global configuration is stored in file config/system/settings.php in Composer-based extensions, typo3conf/system/settings.php in legacy installations.

Changed in version 12.0

For Composer-based installations the configuration files have been moved and renamed:

  • public/typo3conf/LocalConfiguration.php is now available in config/system/settings.php

For legacy installations to:

  • typo3conf/system/settings.php

This file overrides default settings from typo3/sysext/core/Configuration/DefaultConfiguration.php.

The local configuration file is basically a long array which is simply returned when the file is included. It represents the global TYPO3 configuration. This configuration can be modified/extended/overridden by extensions by setting configuration options inside an extension's ext_localconf.php file. See extension files and locations for more details about extension structure.

A typical content of config/system/settings.php looks like this:

config/system/settings.php | typo3conf/system/settings.php
return [
   'BE' => [
      'debug' => true,
      'explicitADmode' => 'explicitAllow',
      'installToolPassword' => '$P$Cbp90UttdtIKELNrDGjy4tDxh3uu9D/',
      'loginSecurityLevel' => 'normal',
   'DB' => [
      'Connections' => [
         'Default' => [
            'charset' => 'utf8',
            'dbname' => 'empty_typo3',
            'driver' => 'mysqli',
            'host' => '',
            'password' => 'foo',
            'port' => 3306,
            'user' => 'bar',
   'EXTCONF' => [
       'lang' => [
           'availableLanguages' => [
   'EXTENSIONS' => [
       'backend' => [
           'backendFavicon' => '',
           'backendLogo' => '',
           'loginBackgroundImage' => '',
           'loginFootnote' => '',
           'loginHighlightColor' => '',
           'loginLogo' => '',
       'extensionmanager' => [
           'automaticInstallation' => '1',
           'offlineMode' => '0',
       'scheduler' => [
           'maxLifetime' => '1440',
           'showSampleTasks' => '1',
   'FE' => [
      'debug' => true,
      'loginSecurityLevel' => 'normal',
   'GFX' => [
      'jpg_quality' => '80',
   'MAIL' => [
      'transport_sendmail_command' => '/usr/sbin/sendmail -t -i ',
   'SYS' => [
      'devIPmask' => '*',
      'displayErrors' => 1,
      'encryptionKey' => '0396e1b6b53bf48b0bfed9e97a62744158452dfb9b9909fe32d4b7a709816c9b4e94dcd69c011f989d322cb22309f2f2',
      'exceptionalErrors' => 28674,
      'sitename' => 'New TYPO3 site',

As you can see, the array is structured on two main levels. The first level corresponds roughly to a category, the second one being properties, which may themselves be arrays.

The configuration categories are:

Options related to the TYPO3 backend.
Database connection configuration.
Extension installation options.
Backend-related language pack configuration resides here.
Extension configuration.
Frontend-related options.
Options related to image manipulation..
Settings for tuning HTTP requests made by TYPO3.
Configuration of the logging system.
Options related to the sending of emails (transport, server, etc.).
Service API configuration.
General options which may affect both the frontend and the backend.
Service registration configuration and the backend.

Further details on the various configuration options can be found in the Admin Tools module as well as the TYPO3 source at EXT:core/Configuration/DefaultConfigurationDescription.yaml. The documentation shown in the Admin Tools module is automatically extracted from those values of DefaultConfigurationDescription.yaml.

The Admin Tools module provides various dedicated sections that change parts of config/system/settings.php, those can be found in Admin Tools > Settings, most importantly section Configure installation-wide options:

Configure installation-wide options Admin Tools > Settings

Configure installation-wide options with an active search

File config/system/additional.php

Although you can manually edit the config/system/settings.php file, it is limited in scope because the file is expected to return a PHP array. Also the file is rewritten every time an option is changed in the Install Tool or some other operation (like changing an extension configuration in the Extension Manager). Thus custom code cannot reside in that file.

Such code should be placed in the config/system/additional.php file. This file is never touched by TYPO3, so any code will be left alone.

Changed in version 12.0

For Composer-based installations the configuration files have been moved and renamed:

  • public/typo3conf/AdditionalConfiguration.php is now available in config/system/additional.php

For legacy installations to:

  • typo3conf/system/additional.php

Furthermore this file is loaded after config/system/settings.php, which means it represents an opportunity to change global configuration values programmatically if needed.

config/system/additional.php is a plain PHP file. There are no specific rules about what it may contain. However, since the code is included on every request to TYPO3 - whether frontend or backend - you should avoid inserting code which requires a lot of processing time.

Example: Changing the database hostname for development machines

config/system/additional.php | typo3conf/system/additional.php

$applicationContext = \TYPO3\CMS\Core\Core\Environment::getContext();
if ($applicationContext->isDevelopment()) {
    $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['host'] = 'mysql-be';

File DefaultConfiguration.php

TYPO3 comes with some default settings, which are defined in file EXT:core/Configuration/DefaultConfiguration.php.

This is the base configuration, the other files like config/system/settings.php just overlay it.

Here is an extract of that file:

return [
    'GFX' => [
        'thumbnails' => true,
        'thumbnails_png' => true,
        'gif_compress' => true,
        'imagefile_ext' => 'gif,jpg,jpeg,tif,tiff,bmp,pcx,tga,png,pdf,ai,svg',
        // ...
    // ...

It is certainly interesting to take a look into this file, which also contains values that are not displayed in the Install Tool and therefore cannot be changed easily.