Media Files Addon

This addon allows you to push and pull your files in the Media Library between two WordPress installs. The addon can be used in two ways: it can compare both libraries and only migrate those missing or updated, or it can do a complete copy of one site’s library to another.


Comparing media

Compare then <upload|download>

This option is great for migrations between sites that have already had migrations in the past, and the sites need synchronizing again. The addon will scan both sites’ Media Libraries to work out which files need to be migrated.

For example, let’s say you’ve copied the entire uploads folder of Site A to Site B. Now they both currently have 300 media files. On Site A, you decide to add 5 images. When pushing from Site A to Site B the addon will simply copy the missing 5 media files (plus any resized images) to Site B. The original 300 media files will not be migrated.

Push migrations will compare remote and local media files and only upload those missing or updated to the remote site.
Pull migrations will compare remote and local media files and only download those missing or updated to the local site.

Compare, <upload|download> then remove

This option operates identically to the previous one, except at the end of the migration the addon will remove files on the target site that do not exist on the source site.

As an example, let’s say you have two sites: Site A and Site B that you would like to sync up. Since the last migration Site A has had 20 new images added, and Site B has had 10. When you push from Site A to Site B with the “Compare, upload then remove” option enabled, the 20 images from A will be migrated, and the plugin will remove the 10 image files from Site B, ensuring the uploads folders are in complete sync.

Complete media migration

Remove all then <upload|download> all

Sometimes you just want to copy the whole Media Library from one site to another during a migration and this option makes that a breeze. The addon will completely remove all files from the target site and copy over all files from the source site.

Push migrations will remove all remote media files and upload all local media files to the remote site.
Pull migrations will remove all local media files and download all remote media files to the local site.


If you are working with a multisite installation and would like to only transfer files for certain subsites, you can check the box next to “Only transfer files for selected subsites” and then select which subsites’ files you’d like to transfer. This option only effects the media files transfer, so when selecting tables to migrate you should be sure to only select wp_#_posts and wp_#_postmeta tables for the subsites that you’ll be transferring media for.


The addon integrates seamlessly with our CLI addon that lets you leverage the power of WP-CLI for performing migrations from the command line. When running existing profiles from the CLI, you now get a more informative display of the media migrations process:


If you run CLI migrations on the fly with migration parameters you can use the –media parameter to specify the various options –

Things to remember

It is important to note that migrations which skip the comparison and remove all files from the target site before migrating files from the source, will also remove files that are not part of the target site’s Media Library but reside within the /wp-content/uploads folder, such as files created by other plugins and any manually uploaded.

Only files listed in your WordPress Media Library will be migrated. The addon will not migrate any files in your uploads folder that are not listed in the Media Library.

If you are selecting only certain tables as part of the database migration and you intend to migrate media, you will need to include the ‘wp_posts’ and ‘wp_postmeta’ tables in the migration.


To ensure media migrations are successful, make sure that your uploads folder is writable. Depending on your web host, you may need to set the permissions on your uploads folder and any subfolders to 775.

If any of the files fail to migrate you should be presented with a list of the failures upon migration completion. These are often non-fatal errors, meaning that the rest of the migration should have completed just fine.

Unicode-encoded filenames & Windows

On Windows, the PHP filesystem wrapper expects and returns ISO-8859-1 strings for file/directory names. Non-ASCII characters will appear incorrect outside PHP. A non-ASCII UTF-8 char will be stored as multiple single ISO-8859-1 characters. E.g. ó will be appear as ó in Windows Explorer.

As it stands, you can’t load files with Unicode-encoded filenames into the WordPress media library and have them work on Windows. Similarly, WP Migrate DB Pro cannot migrate files which have Unicode-encoded filenames on Windows. Learn more about how Unicode works in this article by our very own Peter Tasker.