Skip to content

Add media to a VIP Local Development Environment

Media files can be uploaded, imported, or proxied to a running VIP Local Development Environment. It is recommended to import media files after a VIP Local Development Environment is confirmed to be up and running and has been configured to run with locally cloned application code.


On the user’s local machine a VIP Local Development Environment has been successfully created and is in a running state.


  • The VIP Local Development Environment does not include a replica of the VIP File System. When developing features for an application that rely on the VIP File System service, it is strongly recommended to stage changes and perform tests on a non-production VIP Platform environment instead of the VIP Local Development Environment.
  • A VIP Local Development Environment will be unable to proxy media files (the --media-redirect-domain option) from a WordPress multisite environment that has the Access-controlled files feature activated.

Location of the uploads directory

Media files that are imported—or uploaded with the WordPress media uploader—to the local environment are stored in a local uploads/ directory that is mapped to a local environment’s LOCATION URL.

To locate a local environment’s uploads/ directory, retrieve the LOCATION URL of the local environment with vip dev-env info. For example:

$ vip dev-env info --slug=example-site
  SLUG              example-site                                                                                          
 LOCATION          /Users/example-user/.local/share/vip/dev-environment/example-site                                             
 SERVICES          devtools, nginx, php, database, memcached, wordpress, vip-mu-plugins, demo-app-code                   
 NGINX URLS                                                                 
 STATUS            UP 

Based on the output of the above command example, the uploads/ directory can be found at:

Import media files with VIP-CLI

After importing a VIP Platform environment’s database to the local environment, media files may not appear as expected on the front end of the local site or in the WordPress Media Library. To remedy this, media files must be imported to the local site’s uploads/ directory and media file URLs in the database must map correctly to that local directory.

  1. Download a Media Backup for a VIP Platform environment from the VIP Dashboard.
  2. Decompress the downloaded  *.zip file.
  3. Import the /uploads/ directory, located in the decompressed file structure: /wp-content/uploads/ using the VIP-CLI command vip dev-env import media <path-to-uploads-directory>.

In this command example, the contents of /Users/example-user/Desktop/wp-content/uploads will be imported to the uploads/ directory that is mapped to the LOCATION URL of a local environment with an assigned --slug value example-site:

vip dev-env import media --slug=example-site /Users/example-user/Desktop/wp-content/uploads

If the media files do not load on the local site as expected after completing the above steps, a search and replace operation may need to be performed on the database.

Use exec to execute WP-CLI commands such as search-replace against the local environment’s database. The search-replace operations should update media file URLs in the database to point to the location of the imported media files in the local uploads/ directory.

For example, if a user imported a database backup and a media backup of their production site into their VIP Local Development Environment, the media file URLs in the local environment’s database should be updated by searching for the string and replacing it with

vip dev-env exec --slug=example-site -- wp search-replace --all-tables --dry-run

Proxy media files

After importing a VIP Platform environment’s SQL database to the local environment, media file requests can be proxied to the VIP Platform environment where the database originated. This eliminates the need to download and import media files to a local machine.

To enable media URLs in the local database to proxy to the VIP Platform environment, set the --media-redirect-domain option to the VIP Platform environment’s primary domain.

The --media-redirect-domain option can be set when creating a VIP Local Development Environment, or with the update subcommand for an existing local environment.

In this command example, a local environment is created with the assigned --slug value example-site, and --media-redirect-domain is configured to proxy media requests to the VIP Platform production site with the primary domain

vip dev-env create --slug=example-site

Requests for a media file will first refer to the local uploads/ directory that is mapped to a local environment’s LOCATION URL. If the requested media file is not found there, a 404 is returned. The request is then redirected to the uploads/ directory of the domain that was assigned to the --media-redirect-domain option.

To work as expected:

  • A search-replace operation must have been completed on the database to replace VIP Platform environment domain values (e.g. with local domain values (e.g.
  • Local domain values must have a subdomain structure (e.g. and not a subdirectory structure (e.g.

Last updated: July 09, 2024

Relevant to

  • WordPress