---
title: "File imports"
manual: "TypoScript Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3tsref:typoscript-syntax-includes@13.4"
source: "Syntax/FileImports/Index.rst"
rendered: "2026-10-04T15:44:05+00:00"
---

# File imports {#typoscript-syntax-includes}

<!-- TODO: no Markdown rendering for "deprecated" -->

The old school <INCLUDE_TYPOSCRIPT: syntax has been deprecated
and will be removed with TYPO3 v14.0. See migrating the TypoScript includes.

To structure and reuse single TypoScript snippets and not stuffing everything
into one file or record, the syntax allows loading TypoScript content from sub files.

The keyword `@import` is a syntax construct and
thus available in both frontend TypoScript and backend TSconfig.

`@import` allows including additional files using wildcards on the file
level. Wildcards in paths are not allowed.

The TypoScript parser allows to place `@import` within condition
bodies, which allows conditional imports with `@import`.

`@import` is not allowed to be placed within code blocks
and breaks any curly braces level, resetting current scope
to top level.

## @import {#typoscript-syntax-import}

This keyword allows including files inspired by a syntax similar to `SASS`.
It is restricted, but still allows wildcards on file level. Single files *must* end
with `.typoscript` if included in frontend Typoscript. In backend TSconfig,
single files *should* end with `.tsconfig`, but *may* end with
`.typoscript` as well (for now).

The include logic is a bit more restrictive with TYPO3 v12, previous versions
have been slightly more relaxed in this regard. See
[this changelog](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/12.0/Breaking-97816-TypoScriptSyntaxChanges.html)
for more details.

The following rules apply:

-   Multiple files are imported in alphabetical order.
    If a special loading order is desired it is common to prefix the filenames with
    numbers that increase for files that shall be loaded later.
-   Recursion is allowed: Imported files can have `@import` statements.
-   The `@import` statement does not take a condition clause as the old
    `<INCLUDE_TYPOSCRIPT condition="">` statement did. That kind of condition
    should be considered a conceptual mistake. It should not be used.
-   <!-- TODO: no Markdown rendering for "versionchanged" -->

    It is allowed to put `@import` within a condition. This example imports
    the additional file only if a frontend user is logged in:

    ```typoscript
    [frontend.user.isLoggedIn]
        @import './userIsLoggedIn.typoscript'
    [END]
    ```
-   Both the old syntax `<INCLUDE_TYPOSCRIPT>` and the new one `@import`
    can be used at the same time.
-   Directory imports are not recursive, meaning that a directory import does
    not automatically travel down its subdirectories.
-   Quoting the filename is necessary with the new syntax. Either double quotes
    (") or single quotes (') can be used.
-   Wildcards `*` are only allowed on file level, not on directory level.
    Only a single wildcard character is allowed.
-   Includes relative to the current file location are allowed using `./`
    as prefix.
-   Includes must start with `EXT:` if not relative. Loading files
    outside of extensions is not possible.
-   Directory traversal using `../` is not allowed.

Some examples:

**EXT:my_sitepackage/Configuration/Sets/Main/setup.typoscript**

```typoscript
# Import a single file
@import 'EXT:my_extension/Configuration/TypoScript/randomfile.typoscript'

# Import multiple files in a single directory, sorted by file name
@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'

# It's possible to omit the file ending. For frontend TypoScript, ".typoscript" is
# appended automatically, backend TSconfig allows both ".typoscript" and ".tsconfig"
@import 'EXT:my_extension/Configuration/TypoScript/'

# Import files starting with "foo", ending with ".typoscript" (frontend)
@import 'EXT:my_extension/Configuration/TypoScript/foo*'

# Import files ending with ".setup.typoscript"
@import 'EXT:my_extension/Configuration/TypoScript/*.setup.typoscript'

# Import "bar.typoscript" relative to current file
@import './bar.typoscript'

# Import all ".setup.typoscript" files in sub directory relative to current file
@import './subDirectory/*.setup.typoscript'

```

## Alternatives to using file imports {#typoscript-syntax-includes-alternatives}

The following features can make file inclusion unnecessary:

-   [Automatic global inclusion of user TSconfig of extensions](https://docs.typo3.org/permalink/t3tsref:usersettingdefaultusertsconfig@13.4)
-   [Automatic global inclusion of page TSconfig of extensions](https://docs.typo3.org/permalink/t3tsref:pagesettingdefaultpagetsconfig@13.4)
-   [Automatic page TSconfig on site level](https://docs.typo3.org/permalink/t3tsref:include-static-page-tsconfig-per-site@13.4)
-   [TypoScript provider for sites and sets](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ApiOverview/SiteHandling/SiteSets.html#site-sets-typoscript)
    automatically loads TypoScript per site when the site set is included in the
    site configuration.

## Migration from `<INCLUDE_TYPOSCRIPT:` to `@import` {#typoscript-syntax-includes-migration}

> [!IMPORTANT]
> `@import` does not support recursively including all `.typoscript`
> files from sub directories. You need to list each directory with its own
> `@import` statement.
> See [Migrating recursive TypoScript file inclusion](https://docs.typo3.org/permalink/t3tsref:typoscript-syntax-includes-migration-recursive@13.4).

> [!IMPORTANT]
> `@import` supports the file endings `.typoscript` and `.tsconfig`
> only. All other file names will be ignored. Rename all TypoScript files to
> these endings.

Most usages of `<INCLUDE_TYPOSCRIPT:` can be turned into `@import`
easily. A few examples:

```diff
-<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_extension/Configuration/TypoScript/myMenu.typoscript">
+@import 'EXT:my_extension/Configuration/TypoScript/myMenu.typoscript'

 # Including .typoscript files in a single (non recursive!) directory
-<INCLUDE_TYPOSCRIPT: source="DIR:EXT:my_extension/Configuration/TypoScript/" extensions="typoscript">
+@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'

# Including .typoscript and .ts files in a single (non recursive!) directory
-<INCLUDE_TYPOSCRIPT: source="DIR:EXT:my_extension/Configuration/TypoScript/" extensions="typoscript,ts">
+@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'
 # Rename all files ending from .ts to .typoscript

 # Including a file conditionally
-<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_extension/Configuration/TypoScript/user.typoscript" condition="[frontend.user.isLoggedIn]">
+[frontend.user.isLoggedIn]
+    @import 'EXT:my_extension/Configuration/TypoScript/user.typoscript'
+[END]
```

There are a few more use cases that cannot be transitioned so easily since
`@import` is a bit more restrictive.

As one restriction `@import` cannot include files from arbitrary directories
like `fileadmin/`, but only from extensions by using the `EXT:`
prefix. Instances that use `<INCLUDE_TYPOSCRIPT:` with `source="FILE:./someDirectory/..."`
should move these TypoScript files into a project or site extension. Such instances are also encouraged to
look into the TYPO3 v13 [Site sets](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ApiOverview/SiteHandling/SiteSets.html#site-sets) feature and eventually transition towards it along the way.

`@import` allows to import files with the file ending `.typoscript`
and `.tsconfig`. If you used any of the outdated file endings like `.ts` or
`.txt` rename those files before switching to the `@import` syntax.

### Migrating recursive TypoScript file inclusion {#typoscript-syntax-includes-migration-recursive}

If you have such a tree of TypoScript files:

-   EXT:my_sitepackage/Configuration/TypoScript/
    -   Setup
        -   Extensions
            -   Solr
                -   indexing.typoscript
                -   searchPlugin.typoscript
            -   news.typoscript
            -   tt_address.typoscript
        -   ContentElements
            -   file1.typoscript
            -   file2.typoscript
            -   file3.typoscript
        -   myProject.typoscript
        -   someSettings.typoscript
    -   setup.typoscript

Each directory **must** be listed separately for inclusion when migrating to
the `@import` statement:

**EXT:my_sitepackage/Configuration/TypoScript/setup.typoscript (Difference)**

```diff
-<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_sitepackage/Configuration/TypoScript/Setup">

+@import 'EXT:my_sitepackage/Configuration/TypoScript/Setup'
+@import 'EXT:my_sitepackage/Configuration/TypoScript/Extensions'
+@import 'EXT:my_sitepackage/Configuration/TypoScript/Extensions/Solr'
+@import 'EXT:my_sitepackage/Configuration/TypoScript/ContentElements'
```

The need for recursive includes may also be mitigated by restructuring
TypoScript based functionality using [Site sets](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ApiOverview/SiteHandling/SiteSets.html#site-sets).