---
title: "File imports"
manual: "TypoScript Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3tsref:typoscript-syntax-includes@main"
source: "Syntax/FileImports/Index.rst"
rendered: "2026-09-19T06:55:14+00:00"
---

# File imports {#typoscript-syntax-includes}

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

The old school <INCLUDE_TYPOSCRIPT: syntax has been deprecated
with version 13.4 and was removed with TYPO3 v14.0.
See Migration from <INCLUDE_TYPOSCRIPT: to @import.

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.
-   <!-- 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]
    ```
-   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:site_package/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@main)
-   [Automatic global inclusion of page TSconfig of extensions](https://docs.typo3.org/permalink/t3tsref:pagesettingdefaultpagetsconfig@main)
-   [Automatic page TSconfig on site level](https://docs.typo3.org/permalink/t3tsref:include-static-page-tsconfig-per-site@main)
-   [TypoScript provider for sites and sets](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/SiteSets/Index.html#site-sets-typoscript)
    automatically loads TypoScript per site when the site set is included in the
    site configuration.