Title: Limitations and requirements for media file imports
Author: WordPress VIP Documentation
Published: December 12, 2025
Last modified: March 11, 2026

---

 1. [VIP File System](https://docs.wpvip.com/vip-file-system/)
 2. [Import media files](https://docs.wpvip.com/vip-file-system/import-media-files/)
 3. Limitations and requirements for media file imports

#  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 can only be imported to a production environment.** Media files that 
   are imported to a WordPress production environment are [automatically shared](https://docs.wpvip.com/vip-file-system/shared-media-files/)
   with and available to associated non-production environments.
 * **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](https://docs.wpvip.com/databases/import/) or a [data sync](https://docs.wpvip.com/databases/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](https://docs.wpvip.com/vip-support/#h-contacting-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](https://wordpress.org/support/article/editing-wp-config-php/#moving-uploads-folder)(
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](https://docs.wpvip.com/wordpress-multisite/) will differ from
[WordPress single sites](https://docs.wpvip.com/wordpress-single-site/).

The [`uploads/` file path](https://wordpress.org/support/article/multisite-network-administration/#uploaded-file-path)
for the main site (ID 1) of the multisite will be`uploads/`, 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](https://wordpressvip.zendesk.com/)
requesting assistance with the import and include a downloadable link for the archived
file.

Last updated: March 11, 2026