---
title: "File imports"
manual: "TypoScript Explained"
version: "14.3"
permalink: "https://docs.typo3.org/permalink/t3tsref:typoscript-syntax-includes@14.3"
source: "Syntax/FileImports/Index.rst"
rendered: "2026-10-01T16:17:37+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 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.
-   <!-- 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: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@14.3)
-   [Automatic global inclusion of page TSconfig of extensions](https://docs.typo3.org/permalink/t3tsref:pagesettingdefaultpagetsconfig@14.3)
-   [Automatic page TSconfig on site level](https://docs.typo3.org/permalink/t3tsref:include-static-page-tsconfig-per-site@14.3)
-   [TypoScript provider for sites and sets](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/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.