---
title: "System configuration and the global settings.php"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:typo3confvars@main"
source: "Configuration/Typo3ConfVars/Index.rst"
rendered: "2026-09-18T15:39:49+00:00"
---

# System configuration and the global `settings.php` {#typo3confvars}

System configuration settings, such as database credentials, logging levels, mail
settings, etc, are stored in the central file `system/settings.php`.

This file is primarily managed by TYPO3. Settings can be changed in
the **System > Settings** module by users with the
[system maintainer](https://docs.typo3.org/permalink/t3coreapi:system-maintainer@main)
role.

The file `system/settings.php` is created during the
[setup process](https://docs.typo3.org/permalink/t3coreapi:installation-setup@main).

Configuration options are stored internally in the global array
`$GLOBALS['TYPO3_CONF_VARS']`.

They can be overridden in the file  `system/additional.php`. Some settings
can also be overridden by installed extensions. They are then defined in extension file
[ext_localconf.php](https://docs.typo3.org/permalink/t3coreapi:ext-localconf-php@main)
for the frontend and backend contexts.

This chapter describes the global configuration in more detail and gives hints
about further configuration possibilities.

**Table of contents**

-   [System configuration files](https://docs.typo3.org/permalink/t3coreapi:system-configuration-files@main)
-   [System configuration categories](https://docs.typo3.org/permalink/t3coreapi:system-configuration-categories@main)
-   [File DefaultConfiguration.php](https://docs.typo3.org/permalink/t3coreapi:file-defaultconfiguration-php@main)

## System configuration files {#configuration-files}

The configuration files [`settings.php`](#file-project-config-system-settings-php) and
[`additional.php`](#file-project-config-system-additional-php) are located in the directory
[config/system/](https://docs.typo3.org/permalink/t3coreapi:directory-config-system@main) in Composer-based
installations. In Classic mode installations they are located in
[typo3conf/system/](https://docs.typo3.org/permalink/t3coreapi:classic-directory-typo3conf-system@main).

This path can be retrieved from the Environment API. See
[getConfigPath()](https://docs.typo3.org/permalink/t3coreapi:environment-config-path@main) for both Composer-based and Classic mode installations.

Global configuration is stored in file `config/system/settings.php` in
Composer-based extensions and `typo3conf/system/settings.php` in Classic mode
installations.

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

### File `config/system/settings.php` {#typo3confvars-localconfiguration}

-   **settings.php**

    -   *Scope:* project
    -   *Path (Composer):* config/system/settings.php
    -   *Path (Classic):* typo3conf/system/settings.php

    The most important configuration file is
    `settings.php`. It contains local settings in the
    main global PHP array `$GLOBALS['TYPO3_CONF_VARS']`, for example,
    important settings like database connection credentials are in here. The file
    is managed in the module **System > Settings**.

> [!NOTE]
> The [`settings.php`](#file-project-config-system-settings-php) file can be read-only. In this case, the
> sections in the Install Tool that would write to this file inform a
> system maintainer that it is write-protected. All input fields are disabled
> and the save button not available.

The local configuration file is basically a long array which is 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`](https://docs.typo3.org/permalink/t3coreapi:ext-localconf-php) file. [See extension files and locations](https://docs.typo3.org/permalink/t3coreapi:extension-files-locations@main)
for more details about extension structure.

`config/system/settings.php` typically looks like this:

**config/system/settings.php | typo3conf/system/settings.php**

```php
<?php

return [
  'BE' => [
    'debug' => true,
    'explicitADmode' => 'explicitAllow',
    'installToolPassword' => '$P$Cbp90UttdtIKELNrDGjy4tDxh3uu9D/',
    'loginSecurityLevel' => 'normal',
  ],
  'DB' => [
    'Connections' => [
      'Default' => [
        'charset' => 'utf8',
        'dbname' => 'empty_typo3',
        'driver' => 'mysqli',
        'host' => '127.0.0.1',
        'password' => 'foo',
        'port' => 3306,
        'user' => 'bar',
      ],
    ],
  ],
  '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',
  ],
  'LANG' => [
    'availableLocales' => [
      'de',
      'eo',
    ],
  ],
  '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 categories and the second level to properties, which
may themselves be arrays.

-   **additional.php**

    -   *Scope:* project
    -   *Path (Composer):* config/system/additional.php
    -   *Path (Classic):* typo3conf/system/additional.php

    The settings in `settings.php`  can be overridden by changes in the
    `additional.php` file, which is never touched by TYPO3
    internal management tools. Be aware that having settings within
    `additional.php` may prevent the system from performing
    automatic upgrades and should be used with care and only if you know what
    you are doing.

### File config/system/additional.php {#typo3confvars-additionalconfiguration}

Although you can manually edit the `config/system/settings.php`
file, the changes that you can make are limited 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 other operations (like changing
an extension configuration in the Extension Manager) so do not put custom
code in this file.

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

As this file is loaded **after** `config/system/settings.php`,
you can make programmatic changes to global configuration values here.

`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 in **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**

```php
<?php

use TYPO3\CMS\Core\Core\Environment;

$applicationContext = Environment::getContext();

if ($applicationContext->isDevelopment()) {
  $GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive(
    $GLOBALS['TYPO3_CONF_VARS'],
    [
      // Use DDEV default database credentials during development
      'DB' => [
        'Connections' => [
          'Default' => [
            'dbname' => 'db',
            'driver' => 'mysqli',
            'host' => 'db',
            'password' => 'db',
            'port' => '3306',
            'user' => 'db',
          ],
        ],
      ],
      // This mail configuration sends all emails to mailpit
      'MAIL' => [
        'transport' => 'smtp',
        'transport_smtp_encrypt' => false,
        'transport_smtp_server' => 'localhost:1025',
      ],
      // Allow all .ddev.site hosts
      'SYS' => [
        'trustedHostsPattern' => '.*.ddev.site',
      ],
    ],
  );
}

```

## System configuration categories {#typo3-conf-vars-system-configuration-categories}

-   **BE**

    [Options related to the TYPO3 backend](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-be@main).

-   **DB**

    [Database connection configuration](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-db@main).

-   **EXT**

    [Extension installation options](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-ext@main).

-   **EXTCONF**

    Backend-related language pack configuration resides here.

-   **EXTENSIONS**

    [Extension configuration](https://docs.typo3.org/permalink/t3coreapi:extension-configuration@main).

-   **FE**

    [Frontend-related options](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-fe@main).

-   **GFX**

    [Options related to image manipulation.](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-gfx@main).

-   **HTTP**

    [Settings for tuning HTTP requests](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-http@main) made by TYPO3.

-   **LOG**

    [Configuration of the logging system](https://docs.typo3.org/permalink/t3coreapi:logging-configuration@main).

-   **MAIL**

    [Options related to the sending of emails](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-mail@main)
    (transport, server, etc.).

-   **SVCONF**

    [Service API configuration](https://docs.typo3.org/permalink/t3coreapi:services-developer-service-api-getters@main).

-   **SYS**

    [General options](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-sys@main) which may affect both the
    frontend and the backend.

-   **T3_SERVICES**

    [Service registration configuration](https://docs.typo3.org/permalink/t3coreapi:services-configuration-registration-changes@main)
    and the backend.

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

The **System > Settings** module provides various sections that
change parts of `config/system/settings.php`. They can be found in
**System > Settings** \- most importantly section
**Configure installation-wide options**:

![](../../Images/ManualScreenshots/AdminTools/AllConfiguration.png)

![](../../Images/ManualScreenshots/AdminTools/InstallationWideOptions.png)

## File `DefaultConfiguration.php` {#typo3confvars-defaultconfiguration}

TYPO3 comes with some default settings which are defined in
file `EXT:core/Configuration/DefaultConfiguration.php`. View the
file on GitHub: [EXT:core/Configuration/DefaultConfiguration.php (GitHub)](https://github.com/typo3/typo3/blob/main/typo3/sysext/core/Configuration/DefaultConfiguration.php).

This file defines configuration defaults that can be overridden in the files
`config/system/settings.php` and `config/system/additional.php`.

**vendor/typo3/cms-core/Configuration/DefaultConfiguration.php (Extract)**

```php
<?php

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 interesting to take a look at this file, which also contains
values that are not displayed in the Install Tool and therefore cannot be
changed easily.