---
title: "ext_localconf.php"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:ext-localconf-php@main"
source: "ExtensionArchitecture/FileStructure/ExtLocalconf.rst"
modified: "2026-09-16T13:05:25+00:00"
---

# `ext_localconf.php`

-   **ext_localconf.php**

    -   *Scope:* extension
    -   *Path (Composer):* packages/my_extension/ext_localconf.php
    -   *Path (Classic):* typo3conf/ext/my_extension/ext_localconf.php

    `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`](#file-extension-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](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@main).

Pay attention to the rules for the contents of these files.
For more details, see the [section below](https://docs.typo3.org/permalink/t3coreapi:extension-configuration-files@main).

## Should not be used for

While you *can* put functions and classes into [`ext_localconf.php`](#file-extension-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](https://docs.typo3.org/permalink/t3coreapi:hooks-concept@main), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@main) 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](https://docs.typo3.org/permalink/t3coreapi:logging@main))
-   time zone
-   memory limit
-   locales
-   stream wrapper
-   [error handler](https://docs.typo3.org/permalink/t3coreapi:error-handling-extending@main)
-   Icon registration. Icons should be registered in [Icons.php](https://docs.typo3.org/permalink/t3coreapi:extension-configuration-icons-php@main).

This would not work because the extension files [`ext_localconf.php`](#file-extension-ext-localconf-php) are
included (`loadTypo3LoadedExtAndExtLocalconf`) after the creation of the
mentioned objects in the [Bootstrap](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@main) class.

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

Example:

[Register an exception handler](https://docs.typo3.org/permalink/t3coreapi:error-handling-extending@main):

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

```php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['debugExceptionHandler'] =
    \Vendor\Ext\Error\PostExceptionsOnTwitter::class;
```

## Should be used for

These are the typical functions that extension authors should place within
[`ext_localconf.php`](#file-extension-ext-localconf-php)

-   Registering [hooks](https://docs.typo3.org/permalink/t3coreapi:hooks-concept@main), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@main)
    or any simple array assignments to `$GLOBALS['TYPO3_CONF_VARS']` options
-   Registering additional Request Handlers within the [Bootstrap](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@main)
-   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](https://docs.typo3.org/permalink/t3coreapi:services-developer-service-api@main)

### Examples

Put a file called [`ext_localconf.php`](#file-extension-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`](#file-extension-ext-localconf-php) looks like this:

**EXT:my_extension/ext_localconf.php**

```php
<?php

declare(strict_types=1);

use MyVendor\MyExtension\MyClass;

defined('TYPO3') or die();

// Add your code here
MyClass::doSomething();

```

Read [why the check for the TYPO3 constant is necessary](https://docs.typo3.org/permalink/t3coreapi:globals-constants-typo3@main).