Data import#

The strapi import command is part of the Data Management feature and used to import data from a file. By default, the strapi import command imports data from an encrypted and compressed tar.gz.enc file which includes:

the project configuration,
entities: all of your content,
links: relations between your entities,
assets: files stored in the uploads folder,
schemas,
the metadata.json file.

The archive follows the same structure as the one produced by strapi export: a .tar containing configuration, entities, links, and schemas folders filled with numbered files. Compression (.gz) and encryption (.enc) are detected from the file extension, so a plain .tar can be imported as well.

The following documentation details the available options to customize your data import. The import command and all of the available options are run using the Strapi CLI.

Warning

strapi import deletes all existing data, including the database and uploads directory, before importing the backup file.
The source and target schemas must match to successfully use strapi import, meaning all content types must be identical.
Restored data does not include the Admin users table, which means that createdBy and updatedBy are empty in a restored instance.
If you are using a cloud storage provider (e.g. Cloudinary, AWS S3, Azure Blob Storage, Google Cloud Storage), any media files whose database records are removed during import may be permanently deleted from the cloud provider via its delete API. This affects all environments sharing the same cloud storage account. To avoid unintended deletion of remote assets, ensure each environment uses an isolated storage bucket/account.

Understand the import archive#

strapi import expects an archive with the same flat structure produced by the strapi export command:

configuration/: project configuration files
entities/: entity records
links/: relations between entities
schemas/: schema definitions
metadata.json: metadata about the export

Each folder contains one or more .jsonl files where each line represents a single record. The format allows you to edit or transform data before re‑importing it.

To prepare an archive for manual review or modification:

yarn strapi export --no-encrypt --no-compress -f my-export
tar -xf my-export.tar

npm run strapi export -- --no-encrypt --no-compress -f my-export
tar -xf my-export.tar

After adjusting the .jsonl files, re‑create the archive (tar -cf my-export.tar configuration entities links schemas metadata.json) and import it with strapi import -f my-export.tar. Encryption and compression are detected automatically based on the file extension.

Specify the import file#

To import data into a Strapi instance use the strapi import command in the destination project root directory. Specify the file to be imported using the -f or --file option. The filename, extension, and path are required. If the file is encrypted, you are prompted for the encryption key before the import starts.

Example: Minimum command to import data from a file in the Strapi project root#

yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc

npm run strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc

Example: Import a plain `.tar` archive#

yarn strapi import -f /path/to/my/file/backup.tar

npm run strapi import -- -f /path/to/my/file/backup.tar

Provide an encryption key#

If you are importing data from an encrypted file the encryption key can be passed with the strapi import command by using the -k or --key option.

Example: Pass the encryption key with the `strapi import` command#

yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --key my-encryption-key

npm run strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --key my-encryption-key

Bypass all command line prompts#

When using the strapi import command, you are required to confirm that the import will delete the existing database contents. The --force flag allows you to bypass this prompt. This option is useful for implementing strapi import programmatically. For programmatic use, you must also pass the --key option for encrypted files.

Example of the `--force` option#

yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --force --key my-encryption-key

npm run strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --force --key my-encryption-key

Exclude data types during import#

The default strapi import command imports your content (entities and relations), files (assets), project configuration, and schemas. The --exclude option allows you to exclude content, files, and the project configuration by passing these items in a comma-separated string with no spaces between the types. You can't exclude the schemas, as schema matching is used for strapi import.

Example: exclude assets from an import#

yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --exclude files

npm strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --exclude files

Include only specified data types during import#

The default strapi import command imports your content (entities and relations), files (assets), project configuration, and schemas. The --only option allows you to export only the listed items by passing a comma-separated string with no spaces between the types. The available values are content, files, and config. Schemas are always imported, as schema matching is used for strapi import.

Example: import only the project configuration#

yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --only config

npm strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --only config