Limitations and requirements for media file imports

When importing media files with the VIP-CLI command vip import media, several limitations apply:

• Only one media import per environment can be run at a single time. Attempts to start a second import while a previous import is still in progress will result in an error.
• Media should only be imported to a production environment. Media files that are imported to a WordPress production environment are automatically shared with and available to associated non-production environments. For this reason, importing media to non-production environments is generally unnecessary.
• Files imported with VIP-CLI will not appear in a site’s WordPress media library unless the attachment data for the files exists in the database as a result of a database import or a data sync (for non-production environments).
• Media files that are imported to a WordPress application without an associated database record cannot be deleted without assistance. To delete files without a database entry, contact VIP Support.
• The directory that contains the files for import must be archived with extension *.tar.gz, *.tgz, or *.zip.
• The maximum size of the entire archive that holds the files to be imported is 200 GB.
• The maximum size for an individual file is 4 GB.
• The maximum character length of a file path is 255. This includes the /wp-content/uploads/ prefix in every imported file path.
• Importing a file archive will fail if the provided local path or remote URL ends with a trailing forward-slash (i.e. /).
• Import will fail for a media file within the file archive if it lacks a file extension.
• Hidden files or files within hidden directories will be ignored; they will not be imported. In addition, hidden files will not be included in the count of files that are discovered by the vip import media command, nor will they included in the final count of files that are successfully imported.

Required directory structure

The archived file for import must decompress to a directory named uploads, and only contain the media required for import to a site(s).

If the top-most directory of a decompressed archive file is not named uploads.

• Only the files located within any directory named uploads/ found within the archive’s directory structure will be imported. All other files will be ignored.
• If no directories named uploads/ exist within an archive, the import tool will import the contents of the archive to an environment’s uploads/ directory with the archive’s existing directory structure.

Structure of the uploads directory

In most cases, media that is uploaded to a WordPress site is stored in a directory named uploads/, which is a subdirectory of wp-content/. To prepare media files for migration and import to VIP, an archived copy of a site’s uploads/ directory is recommended.

If a non-VIP WordPress site has customized the name of the uploads/ directory (e.g. files/), the directory should be cloned to a working location and renamed to uploads before being archived and imported to VIP.

Structure of the uploads directory for WordPress multisite

The subdirectory structure of the uploads/ directory for sites belonging to a WordPress multisite will differ from WordPress single sites.

The uploads/ file path for the main site (ID 1) of the multisite will beuploads/, but all other sites on a multisite network will be in the uploads/sites/ directory structure, in their own subfolder based on their network site ID, designated by the database.

Upload paths for all sites other than the main site (ID 1) follow the pattern uploads/sites/{SITE ID}/{YYYY}/{MM}/{FILE NAME}. The values for {SITE ID} do not have any leading 0’s (i.e., use 2, not 02).

If the archived file for import cannot be reformatted or restructured to meet the above requirements, create a VIP Support ticket requesting assistance with the import and include a downloadable link for the archived file.