Bulk Migration Tool
The bulk migration tool offloads media that is already in your Media Library, such as files uploaded before you installed WP Media Cloud. In the plugin it is the Bulk Offload card on the Dashboard. This page also covers the Restore to Server tool and the WP-CLI alternative.
When to use it#

- After you first set up WP Media Cloud. New uploads offload automatically, but older files do not.
- After a period when Offload on upload was switched off.
- After you import records from another offload plugin, to offload anything that plugin had not moved.
- After fixing the cause of failed offloads, to try them again.
Before you start#
- Back up your database and your
wp-content/uploadsfolder. - Open Media Cloud > Health and run the checks. The Loopback Request and WP-Cron checks matter most for the bulk offload.
- Upload one test image and check that it loads from your CDN URL.
- Decide on Remove local files before you start. If it is on, local copies are deleted as each file is offloaded. See Local file removal.
For a large library, consider WP-CLI instead. The Dashboard suggests it for libraries of 5,000 items or more. See Use WP-CLI instead below.
Run a bulk offload#

- Go to Media Cloud > Dashboard.
- In the Bulk Offload card, click Offload All Media. If part of the library is already offloaded, the button reads Continue Offload.
- Watch the progress bar. It shows the percentage of the whole library that is offloaded, plus the offloaded and remaining counts.
- When everything is offloaded, the card shows a Complete badge.
On a new site, the Getting started card has a Start Bulk Offload button that does the same thing. It is disabled until the storage provider is configured.
You can leave the page while it runs. The run continues on the server, and the header shows Offloading with the percentage when you come back.
How it runs in the background#
The bulk offload does not depend on your browser tab.
- When you click the button, your server sends a request to itself (a loopback request to
admin-ajax.php). - That request offloads attachments for up to about 20 seconds, or until PHP memory use reaches 90% of the limit.
- It then saves its place and starts the next request.
- A WP-Cron event every 5 minutes checks the queue. If the chain of requests stopped, it uploads a batch itself and starts the chain again. So the run continues, more slowly, even when loopback requests are blocked (WP Media Cloud 1.1.9 or newer).
Attachments are processed newest first. Each attachment is offloaded like a new upload. That means the main file, every image size and the original image, if WordPress kept one.
Attachments that are already offloaded are skipped, and so are files kept on your server on purpose: font files while Serve fonts from your site is on, videos in Bunny Stream and protected store files. See Automatic offloading.
Stop and continue#
Click Stop Offload to stop the run. Files that were already offloaded stay offloaded.
To continue later, click Continue Offload. A new run looks only for media that is not offloaded yet, so nothing is uploaded twice.
If progress still moves a few seconds after you stop, the current batch was finishing. Click Stop Offload again if it keeps going.
Failed items#

If a file cannot be offloaded, it stays on your server and is served from your site as before. The reason is recorded on the attachment.
Below the progress bar, the card shows how many items failed. Click the line to see each file, its attachment ID and the error. The list shows the 200 most recent failures.
Use wp wpmc failed for the full list.
| Button | What it does |
|---|---|
| Retry all | Tries to offload every listed item again, 5 at a time, and reports how many succeeded and how many still fail |
| Clear | Removes the items from the failed list without retrying. The files stay on your server, and the next bulk offload tries them again |
Every new bulk offload also retries files that failed before, because they are still not offloaded.
| What you see | What it means | How to fix it |
|---|---|---|
Missing file: ... | The file is listed in the Media Library but is not on disk | Restore the file to that path, or delete the attachment |
| An access denied or permission error from your provider | The access key cannot write to the bucket | Check the key’s permissions in your provider’s dashboard |
| A timeout or network error | The provider could not be reached | Click Retry all later |
If the progress does not move#
| What you see | What it means | How to fix it |
|---|---|---|
| Progress moves slowly, or only every few minutes | Your host blocks or delays loopback requests, so the queue only moves when the WP-Cron event runs, every 5 minutes | Check Loopback Request on the Health page. Ask your host to allow requests from the server to itself, or use WP-CLI |
| Progress never moves | Loopback requests are blocked and WP-Cron is not running | Check Loopback Request and WP-Cron on the Health page. If DISABLE_WP_CRON is set, make sure a real cron job calls wp-cron.php. The most reliable fix is WP-CLI |
An alert that says Not configured. | The storage provider settings are incomplete | Finish the setup wizard or complete Settings |
On a server with memory_limit = -1, progress never moved | Older versions read unlimited memory as zero and stopped before every item | Update WP Media Cloud. Current versions treat -1 as unlimited |
| On multisite, a run that was going before an update has stopped | Updating to 1.1.6 or newer moves each subsite’s queue into that subsite. Queue data from older versions is discarded | Start the bulk offload again once on that subsite. Files already offloaded are kept |
Multisite#
Each subsite has its own settings, queue and offload records. Start the bulk offload from each subsite’s own Media Cloud > Dashboard. Runs on different subsites do not block each other.
Network admins can see every site’s progress on the WP Media Cloud: Network Overview page in Network Admin. Subsites can share one bucket when each uses the path prefix sites/%site_id%. Without a prefix, files with the same date and name would overwrite each other, so give each subsite its own bucket. See Custom path prefix.
Use WP-CLI instead#
WP-CLI runs in your terminal. It does not need loopback requests, WP-Cron or a browser tab, so it is faster and more reliable for large libraries.
| Command | What it does |
|---|---|
wp wpmc offload | Offloads everything on this site that is not offloaded yet |
wp wpmc offload --dry-run | Lists what would be offloaded without uploading |
wp wpmc offload --limit=20 | Stops after 20 attachments, for a test run |
wp wpmc offload --batch=100 | Fetches 100 attachments per batch (default 50) |
wp wpmc offload --verbose | Prints each file as it is processed |
wp wpmc offload --retry-failed | Retries only items whose last attempt failed |
wp wpmc offload --network | Runs on every active site in a multisite network |
wp wpmc offload --sites=2,5,9 | Runs on the listed subsites only |
wp wpmc status | Shows provider, total, offloaded, remaining and failed counts |
wp wpmc failed | Lists failed items with the error. Add --clear to forget the recorded errors |
You can stop wp wpmc offload at any time. Running it again continues with whatever is not offloaded yet.
Restore files to your server#
The Restore to Server section at the bottom of the Bulk Offload card downloads offloaded files back into wp-content/uploads. Use it if you switched on Remove local files and need the local copies back, for example before you deactivate the plugin.
- Click Download All to Server.
- Keep the Dashboard tab open. This tool runs from your browser, 5 attachments per request, and stops if you close the tab.
- Wait for Restore complete. Click Re-run to check again, or Stop to stop early.
Files that already exist on your server are skipped. If a download fails, the first error appears under the progress bar.
Restoring does not change your URLs. While Rewrite URLs is on, media is still served from the CDN. The cloud copies are not deleted.
On the command line, wp wpmc restore does the same. It accepts --batch=<n> (default 20), and --network or --sites=<ids> on multisite.