impexp
typo3/cms-impexp
12.4
en
TYPO3 contributors
This document is published under the Open Content License.
Tue, 08 Jul 2025 09:21:57 +0000
This is a tool for importing and exporting records using XML or the custom T3D format.
Table of Contents:
The system extension "Import/Export" (EXT:impexp) allows content to be exported
from one installation of TYPO3 and then imported into another. Exported data
includes content from multiple tables including
tt_ as well as
images and other files stored in fileadmin/.
This extension is often used to manage content for distributions and also training and demonstration purposes.
By default the identifiers are changed when importing data, making it possible to merge several projects into one installation. The table identifiers are automatically changed in such a way that content elements remain attached to their pages and images to their content elements.
It is also possible to keep the identifiers (uids) to allow the reproduction
of the exact same page and content tree.
The data structure for content exports have seen very little changes since their original inception. It is sometimes possible to export content from a fifteen year old TYPO3 installation straight into a current installation of TYPO3.
It is often more feasible to use the import/export tool than it is to attempt to update old installations of TYPO3.
The following images show the export dialog of a current TYPO3 installation and TYPO3 v3.8.0: They correspond pretty much.
Export module of current TYPO3
Export module of TYPO3 3.8.0 (year 2005)
This extension is part of the TYPO3 Core, but not installed by default.
Table of contents
Check whether you are already using the extension with:
composer show | grep impexpThis should either give you no result or something similar to:
typo3/cms-impexp v12.4.11If it is not installed yet, use the composer require command to install
the extension:
composer require typo3/cms-impexpThe given version depends on the version of the TYPO3 Core you are using.
In an installation without Composer, the extension is already shipped but might not be activated yet. Activate it as follows:
Extension manager showing Import / Export extension
The import/export tool can be accessed via the TYPO3 backend or the command line.
Users with admin rights can use both the import and the export functionality. Editors with no admin rights can only use the export functionality (unless it is disabled). Editors can only export content they have access to.
The import functionality can be used for content updates instead of importing the entire page tree and its content.
The export functionality can be used to export initial content for use in distributions.
It is also possible to save and load export data presets for recurring export jobs.
The export functionality is only available for admin users and Backend users for which the Page TSconfig option options.impexp.enableExportForNonAdminUser has been enabled.
Attention
The export functionality has the following security drawbacks:
Thus, permissions should be handed out restrictively.
Go to the export module
In the page tree, right-click the page from which you want to start the export (1) and select More options ... > Export (2).
Select "More options... > Export"
Configure the export
On the first tab of the export module you can fine-tune the export (1).
If you want to export all data of the selected page including its subpages, select the "Infinite" option in the Levels selection box. Under Include tables you can limit the types of records to be exported.
Under Include relations to tables you specify which relations of the records should be included in the export file. The related records will be also included - even if they are outside the pages selected for export.
Under Use static relations for tables you select which relations of the records should be included in the export file - without including the related record. This is useful if the related record already exists in the target TYPO3 instance.
If the same table is selected in Include relations to tables and Use static relations for tables, the relation is treated as static.
The Exclude disabled elements checkbox means, when checked, that these records are excluded from export which are disabled according to their TCA configuration, e.g. by the "disabled", "starttime" or "endtime" fields. It is marked by default.
Apply your changes via the Update button and repeat this step until the preview matches your expectations.
Configure the data to be exported
Check the included records
All pages selected for export are listed in the upper part of the dialog (1).
Below the dialog is a detailed list of all data to be exported (2). Here it is possible to exclude individual records. For some data types it is possible to make them editable manually.
If the relation to records is lost, this is marked with an orange exclamation mark. Reasons for lost relations include records stored outside the page tree to be exported and excluded tables.
Apply your changes by pressing the Update button and repeat this step until the preview is as you want it (3).
Then switch to the Advanced Options tab (4).
Check the exported data
Optionally select advanced export options
In the third tab of the export module you can specify further export options (1).
Checking Save files in extra folder .. means that files linked in records will be saved in a separate folder instead of being included directly in the export file. This is mandatory for use in distributions or when there are a large number of files that would otherwise bloat the export file and exhaust memory. The folder name pattern is "{filename}.files".
Apply your changes by hitting the Update button (2) and switch to tab File & Preset (3) to start the export process.
Select advanced export options
Perform the export
In the second tab of the export module you can specify the metadata of the export (1) before starting the export process.
You can download the export file (2.a) or save it on your server (2.b).
Currently it is necessary to choose saving on the server if the export is configured to save related files in a separate folder (see "Optionally select advanced export options" step).
Download the export data
The import functionality is only available for admin users and Backend users for which the Page TSconfig option options.impexp.enableImportForNonAdminUser has been enabled.
Note
Make sure that any required extensions are installed and the database scheme is up-to-date before starting the import. Otherwise the data related to non-existing tables will not be imported.
Go to the import module
In the page tree, right-click the page you want to import to (1) and select More options ... > Import (2).
Select "More options... > Import"
Upload the export file
On the second tab of the import module you can upload the export file to your target TYPO3 instance.
Select the file to upload (1) and click the Upload files button (2).
Then switch to the Import tab (3).
Upload the export data
Configure the import
On the first tab of the import module you can configure the import.
First select the uploaded export file (1). Then adjust the general settings (2). Finally, press the Preview button (3).
Checking Update records means that existing records with the same UID will be updated instead of newly inserted.
Checking Do not show differences in records prevents calculation of differences between existing and imported records. Note: The compare function is currently broken and therefore disabled in the screenshot.
Configure the import
Check the data to be imported
A tree with the records to be imported is displayed below the configuration form (1). If you change any of the options (2), you can reload this preview with the Preview button (3).
Check and perform the import
Perform the import
Click the Import button.
The import/export tool can be used to synchronize content and page structures between different TYPO3 installations, leaving the content outside the exported page tree unchanged.
During the import check Import > Import Options > Update records:
Update content in an existing structure
Warning
If you have manually excluded records from export, the
uid values of
those exports are saved in the preset. This can lead to unexpected exclusions
if you want to use the preset in another TYPO3 instance. Therefore, check
the excluded records in the tab "Configuration" thoroughly when you have
loaded a preset.
Any configuration settings of the export module are not
automatically saved. If you want to reuse them, you must save them as presets.
Presets are stored internally in the
tx_ table and can be
included in exports by including this table in the export.
Save or load an export preset
To save a new preset, go to Export > File & Preset > Presets, enter a Title of new preset (A.1) and select Save (A.2).
To load a preset, choose the desired preset from Select Preset (B.1) and select Load (B.2).
To modify a preset, load it, make changes to the settings, select the preset in Select Preset again (!) and save it.
Checking Public means that any TYPO3 backend user can load this preset, while otherwise this is restricted to the creator of the preset.
The import/export tool can alternatively also be used via the command line. The advantage of using the CLI is that there is no PHP time limit, therefore larger page trees can be exported and imported.
The exports and imports can be fine-tuned through the complete set of options also available in the import or export module of the TYPO3 backend.
Note
If your TYPO3 installation is based on Composer, you can run the command
with the shortcut
vendor/ instead of
typo3/.
Export the entire TYPO3 page tree (or selected parts of it) to a data file of format XML or T3D:
typo3/sysext/core/bin/typo3 impexp:export [options] [--] [<filename>]with these options available:
Arguments:
filename The filename to export to (without file extension)
Options:
--type[=TYPE] The file type (xml, t3d, t3d_compressed). [default: "xml"]
--pid[=PID] The root page of the exported page tree. [default: -1]
--levels[=LEVELS] The depth of the exported page tree. "-2": "Records on this page", "-1": "Expanded tree", "0": "This page", "1": "1 level down", .. "999": "Infinite levels". [default: 0]
--table[=TABLE] Include all records of this table. Examples: "_ALL", "tt_content", "sys_file_reference", etc. (multiple values allowed)
--record[=RECORD] Include this specific record. Pattern is "{table}:{record}". Examples: "tt_content:12", etc. (multiple values allowed)
--list[=LIST] Include the records of this table and this page. Pattern is "{table}:{pid}". Examples: "be_users:0", etc. (multiple values allowed)
--include-related[=INCLUDE-RELATED] Include record relations to this table, including the related record. Examples: "_ALL", "sys_category", etc. (multiple values allowed)
--include-static[=INCLUDE-STATIC] Include record relations to this table, excluding the related record. Examples: "_ALL", "be_users", etc. (multiple values allowed)
--exclude[=EXCLUDE] Exclude this specific record. Pattern is "{table}:{record}". Examples: "fe_users:3", etc. (multiple values allowed)
--exclude-disabled-records Exclude records which are handled as disabled by their TCA configuration, e.g. by fields "disabled", "starttime" or "endtime".
--exclude-html-css Exclude referenced HTML and CSS files.
--title[=TITLE] The meta title of the export.
--description[=DESCRIPTION] The meta description of the export.
--notes[=NOTES] The meta notes of the export.
--dependency[=DEPENDENCY] This TYPO3 extension is required for the exported records. Examples: "news", "powermail", etc. (multiple values allowed)
--save-files-outside-export-file Save files into separate folder instead of including them into the common export file. Folder name pattern is "{filename}.files".Import an export dump file in XML or T3D format into a TYPO3 instance:
typo3/sysext/core/bin/typo3 impexp:import [options] [--] <file> [<pid>]with these options available:
Arguments:
file The file path to import from (.t3d or .xml).
pid The page to import to. [default: 0]
Options:
--update-records If set, existing records with the same UID will be updated instead of inserted.
--ignore-pid If set, page IDs of updated records are not corrected (only works in conjunction with --update-records).
--force-uid If set, UIDs from file will be forced.
--import-mode[=IMPORT-MODE] Set the import mode of this specific record.
Pattern is "{table}:{record}={mode}".
Available modes for new records are "force_uid" and "exclude" and for existing records "as_new", "ignore_pid", "respect_pid" and "exclude".
Examples are "pages:987=force_uid", "tt_content:1=as_new", etc. (multiple values allowed)
--enable-log If set, all database actions are logged.Exported content may contain sensitive and restricted information related to your site. It is recommended that this extension be deactivated when it is not in use to prevent content being exported in error.
The export function is available by default for editors without admin rights. It is limited to content to which the editor has access. The export functionality can be hidden in the editor's context menu by the user TSconfig contextMenu disableItems.
Note that it cannot be completely disabled as there are currently other entry points.
Exports are stored in fileadmin/.
TYPO3 will automatically create a .htaccess file to prevent access to
this folder from external sources. On Nginx webservers the .htaccess
file has no effect. Follow the Security guidelines for System
Administrators to find out how to prevent
access to specific directories on Nginx webservers.
If you believe you have found a security related issue that is not listed here, please contact the TYPO3 Security Team.
You can check for any known problems in the TYPO3 Core issues on Forge If your issue is not listed, you can also report an issue here. Use the category "Import/Export (T3D)" when reporting your issue.