-- optional

ext_localconf.php is always included in global scope of the script, in the frontend, backend and CLI context.

It should contain additional configuration of $GLOBALS['TYPO3_CONF_VARS'].

This file contains hook definitions and plugin configuration. It must not contain a PHP encoding declaration.

All ext_localconf.php files of loaded extensions are included right after the files config/system/settings.php and config/system/additional.php during TYPO3 bootstrap.

Pay attention to the rules for the contents of these files. For more details, see the section below.

Should not be used for

While you can put functions and classes into ext_localconf.php, it considered bad practice because such classes and functions would always be loaded. Move such functionality to services or utility classes instead.

Registering hooks, XCLASSes or any simple array assignments to $GLOBALS['TYPO3_CONF_VARS'] options will not work for the following:

  • class loader
  • package manager
  • cache manager
  • configuration manager
  • log manager (= Logging Framework)
  • time zone
  • memory limit
  • locales
  • stream wrapper
  • error handler
  • Icon registration. Icons should be registered in Icons.php.

This would not work because the extension files ext_localconf.php are included (loadTypo3LoadedExtAndExtLocalconf) after the creation of the mentioned objects in the Bootstrap class.

In most cases, these assignments should be placed in config/system/additional.php.


Register an exception handler:

config/system/additional.php | typo3conf/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['debugExceptionHandler'] =

Should be used for

These are the typical functions that extension authors should place within file:ext_localconf.php

  • Registering hooks, XCLASSes or any simple array assignments to $GLOBALS['TYPO3_CONF_VARS'] options
  • Registering additional Request Handlers within the Bootstrap
  • Adding any page TSconfig
  • Adding any user TSconfig
  • Adding default TypoScript via \TYPO3\CMS\Core\Utility\ExtensionManagementUtility APIs
  • Registering Scheduler Tasks
  • Adding reports to the reports module
  • Registering Services via the Service API


Put a file called ext_localconf.php in the main directory of your Extension. It does not need to be registered anywhere but will be loaded automatically as soon as the extension is installed. The skeleton of the ext_localconf.php looks like this:



use MyVendor\MyExtension\MyClass;

defined('TYPO3') or die();

// Add your code here

Read why the check for the TYPO3 constant is necessary.

Adding default page TSconfig

Changed in version 12.0

Page TSconfig in a file EXT:some_extension/Configuration/page.tsconfig is loaded globally.

Put all page TSconfig that must always be loaded into file EXT:some_extension/Configuration/page.tsconfig. If your extension should also be compatible with TYPO3 v11, you can additionally load it in the ext_localconf.php: Global page TSconfig, compatible with TYPO3 11 and 12:

Page TSconfig that can be added in the page settings should be added in the file Configuration/TCA/Overrides/pages.php, see Static page TSconfig.

Adding default user TSconfig

As for default page TSconfig, user TSconfig can be added inside ext_localconf.php, see: Setting default user TSconfig:



use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

    '@import "EXT:my_extension/Configuration/defaultUser.tsconfig"',

See also Setting user TSconfig.