Bulk Migration Tool

4 min readUpdated June 27, 2026

The bulk migration tool moves your existing WordPress media library to cloud storage. Files uploaded before WP Media Cloud was installed are not offloaded automatically. The bulk migration tool handles them in a single background operation with no item limits and no page reload required.

When to use the bulk migration tool#

Run the bulk migration tool in any of the following situations:

After first-time setup, to offload media that was uploaded before WP Media Cloud was installed
After switching to a new storage provider, to move files from the old bucket to the new one
After a period where automatic offloading was disabled, to offload files that were saved locally during that time
After migrating from another offload plugin, to ensure all attachments are correctly registered with WP Media Cloud

Before you run the migration#

Take a full backup of your WordPress database and wp-content/uploads directory before running the bulk migration tool. While the tool does not delete local files unless local file removal is enabled, a backup ensures you can recover if something goes wrong mid-migration.

Also confirm that your storage connection is working by running the connection test in WP Media Cloud > Settings > Storage. A failed connection mid-migration will cause files to be skipped without an obvious error.

Running the bulk migration#

Go to WP Media Cloud > Tools > Bulk Migration. You will see a summary of your media library showing the total number of attachments and how many have already been offloaded to cloud storage.

Click Start Migration to begin. The tool processes files in batches in the background. You do not need to keep the page open. The progress bar updates as batches complete. You can navigate away from the page and return to check progress at any time.

What the tool does#

For each attachment in your media library, the bulk migration tool:

Checks whether the file has already been offloaded. If it has, it is skipped.
Uploads the original file and all registered thumbnail sizes to your configured cloud storage bucket.
Updates the WordPress attachment record to reflect the cloud storage location.
If local file removal is enabled, deletes the local copies after a successful upload.

Files are processed in order from oldest to newest. The tool resumes from where it left off if interrupted, so you do not need to start from the beginning if the migration is paused or the page is closed.

No item limits#

The bulk migration tool has no limit on the number of files it can process. Libraries of any size are handled the same way. Very large libraries will naturally take longer to complete, but the background processing means this does not affect your site’s front end while the migration runs.

Pausing and resuming#

Click Pause Migration at any time to stop processing. The current batch will finish before the tool stops. Click Resume Migration to continue from where the tool paused. No files are duplicated or skipped when resuming.

Migration on staging sites#

If you are running the bulk migration on a staging site that shares a storage bucket with production, be careful about local file removal. Deleting local files on staging that are also needed on production will break production if the staging database is later pushed to production without the cloud URLs in place. In most cases, disable local file removal when running the bulk migration on staging.

What happens if the migration stalls#

If the progress bar stops moving and the migration does not appear to be continuing, check the following:

Storage connection — run the connection test in Settings > Storage. A dropped connection will cause the tool to stall on the current batch.
PHP execution time — if your host has a very low max_execution_time, individual batches may time out before completing. Contact your host to increase this limit or switch to a host with more permissive PHP settings.
Memory limit — processing very large image files requires more memory. If PHP runs out of memory mid-batch the tool will stall. Increase WP_MEMORY_LIMIT in wp-config.php if needed.
Background processing blocked — some hosts block the background HTTP requests that WordPress uses for background processing. If the migration will not start or immediately stalls, contact your host to confirm background processing is allowed.

In most cases, clicking Resume Migration after resolving the underlying issue will continue the migration without loss of progress.

Verifying the migration#

When the migration completes, the summary panel will show all attachments as offloaded. To spot-check the result, go to Media > Library, click on any image, and confirm the file URL in the attachment details panel points to your cloud storage bucket or CDN hostname rather than your WordPress site URL.