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 JSON lines 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.
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 thatcreatedBy
andupdatedBy
are empty in a restored instance.
Understand the import archive
strapi import
expects an archive with the same flat structure produced by the strapi export
command:
configuration/
: project configuration filesentities/
: entity recordslinks/
: relations between entitiesschemas/
: schema definitionsmetadata.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
- NPM
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
- npm
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
- npm
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
- npm
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
- npm
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
.
Any types excluded from the import will be deleted in your target instance. For example, if you exclude config
the project configuration in your target instance will be deleted.
Media such as images consist of the file (asset) and the entity in the database. If you use the --exclude
flag to remove assets, the database records are still included, and could render as broken links.
Example: exclude assets from an import
- yarn
- npm
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
.
Media such as images consist of the file (asset) and the entity in the database. If you use the --only
flag to import content
the asset database records are still included, and could render as broken links.
Example: import only the project configuration
- yarn
- npm
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