Documentation

Media Files Addon

This addon allows you to push and pull your files in the Media Library between two WordPress installs.

Installing the Media Files Addon

To download the Media Files Addon, login to My Account and head to the Downloads section of your Licenses tab. Alternatively, you can install the addons directly from your WordPress Dashboard, by navigating to Tools -> Migrate DB Pro -> Addons and click Install under “Media Files”.

Include Media files in a migration

In WP Migrate DB Pro 2.0, we’ve simplified the way the addon works. Now, you can choose between migrating all media files, or only migrate media files added or updated since a specified date.

Migrate all files option checked

Migrate all files

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 copy over all files from the source site to the target site. All files in the uploads folder will be copied to the destination, regardless if they exist at the destination or not.

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

Migrate files created/added since a specified date

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 only migrate media files that have been updated or added since a date you specify during the migration process.

Migrate new files option checked and displaying reference date

In the above example, the addon will only migrate any files added/update since the 1st of January 2021, at 12:30pm.

WP Migrate DB Pro v1.x

Before the WP Migrate DB Pro 2.0 release, the addon had the option to migrate all media files (“Remove all then download all”) but instead of the option to migrate files since a specified date, it allowed for comparing both libraries and only migrate those missing or updated.

media-files-addon-options

Comparing media

Compare then <upload|download>

This option 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.

Multisite

If you are migrating to or from a multisite installation, the media files will be transferred depending on what you are migrating.

If you are migrating from multisite to multisite then the options you select for transferring Media Files would apply to all media files in the entire multisite network. If you are migrating a subsite, either from or to a multisite, then this would apply just to the subsite.

In versions prior to 2.0 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.

WP CLI

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:

new-in-mf-13-and-cli-11-05

If you run CLI migrations on the fly with migration parameters you can use the –media parameter to specify the various options – https://deliciousbrains.com/wp-migrate-db-pro/doc/cli-push-pull-subcommand/

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.

Permissions

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.