How WP Media Cloud works
This page explains what WP Media Cloud does when you upload, view and delete media. Read it to predict what a setting will change and to troubleshoot missing or local URLs.
The short version#
- You upload a file to the Media Library. WordPress saves it to
wp-content/uploadsand creates the image sizes. - WP Media Cloud copies the file and every size to your bucket, and records where each one went.
- When a page loads, the plugin swaps your local uploads address for your CDN address.
- Visitors download the files from your CDN or bucket. Your server no longer serves them.
Offload on upload#

When Offload on upload is on (the default), the plugin offloads each new upload as soon as WordPress has generated its image sizes.
- Block editor and media modal uploads are offloaded before WordPress replies to the editor. The editor shows the CDN address straight away.
- Image optimizers that compress in the background trigger a second offload when they finish. The compressed files then replace the originals in the bucket.
- A safety check runs through WP-Cron about 5 minutes after each upload. It offloads the file if anything above was missed.
Each upload includes the original file, every generated size and, for large images, the original file WordPress kept before scaling. If the main file cannot be uploaded, the whole item counts as failed.
Every file is stored with the header Cache-Control: public, max-age=31536000, immutable, so browsers and CDNs can cache it for a year. When a file is re-uploaded under the same name, for example after an image optimizer compresses it, CDNs and browsers may keep the earlier copy. Purge it from your CDN. When PHP’s cURL extension is available, files are streamed from disk. With S3-type providers, files over 64 MB go up in parts.
Remote keys: where files go in the bucket#
By default, the path of a file in your bucket matches its path inside wp-content/uploads.
| Local file | Remote key |
|---|---|
wp-content/uploads/2026/10/photo.jpg | 2026/10/photo.jpg |
wp-content/uploads/2026/10/photo-300x200.jpg | 2026/10/photo-300x200.jpg |
A Path prefix in Settings puts new offloads in a folder of the bucket, for example media/2026/10/photo.jpg. See Custom path prefix. Font files are not offloaded while Serve fonts from your site is on, the default. See Serve fonts from your site.
Each offloaded attachment gets one record in the plugin’s own database table, wpmc_items with your table prefix. The record holds the provider, bucket and the remote key of every size.
To check one file, open it in the Media Library. The WP Media Cloud field shows Offloaded and the remote key.
URL rewriting on the fly#
WP Media Cloud does not save CDN URLs into your posts or attachment records. When Rewrite URLs is on (the default), it builds them as pages load.
- Attachment URLs, image tags,
srcsetsizes and the media modal get the CDN address, for offloaded files only. - Post content gets the CDN address for files that are offloaded, or whose local copy no longer exists. Files that are not offloaded yet keep their local URL.
- Page builder and custom field data is handled by the matching integration. See the Integrations tab.
A CDN URL is your CDN address plus the remote key. For example, https://example.com/wp-content/uploads/2026/10/photo.jpg becomes https://cdn.example.com/2026/10/photo.jpg.
Because URLs are built at load time:
- A new CDN address takes effect on the next page load. Clear any page cache so cached pages pick it up.
- Deactivating the plugin, or turning off Rewrite URLs, returns every URL to your server at once.
- Page caching plugins store pages that already contain CDN URLs. No extra setup is needed.
Because post content only switches offloaded files to the CDN, images in older posts keep working while a bulk offload runs. This needs WP Media Cloud 1.1.9 or newer.
The optional URL Replace tool (beta) writes CDN URLs into the database instead. Most sites do not need it.
CDN delivery#
The CDN address depends on your provider:
| Provider | Address used |
|---|---|
| Bunny.net | Your pull zone hostname, for example https://myzone.b-cdn.net |
| Cloudflare R2 | The CDN URL you entered: your r2.dev address or a custom domain |
| All other providers | Your CDN URL if you chose a CDN, otherwise the bucket address |
The CDN fetches each file from the bucket on its first request, then serves it from its cache. The first view of a new file can take a second or two longer.
WP Media Cloud does not purge CDN caches. Change the CDN on the Settings tab. After a change, Update all media URLs under Apply to Existing Media updates the CDN address saved with each offload record.
What stays on your server#
- Local copies of offloaded files, unless you turn on Remove local files. That switch deletes each local file once its upload succeeds.
- Files that are not in the Media Library, such as theme images, plugin cache folders and form uploads stored elsewhere.
- Media uploaded before setup, until you run a bulk offload.
- Failed items, until a retry succeeds.
Files that stay local keep loading from your server through their normal URLs.
Need the files back after using Remove local files? On the Dashboard tab, click Download All to Server under Restore to Server. You can also run wp wpmc restore.
Do this before you deactivate the plugin.
Existing media and bulk offload#

To offload media uploaded before setup, click Offload All Media in the Bulk Offload card on the Dashboard tab. It works through every attachment that is not offloaded yet. You can stop it and start again; it continues where it left off.
The bulk offload runs in the background through a loopback request, a call from your server to itself. WP-Cron checks on it every 5 minutes as a backup and uploads a batch itself if the run has stopped.
If your host blocks loopback requests, the run still moves forward each time WP-Cron runs, only more slowly. This needs WP Media Cloud 1.1.9 or newer. The Health tab checks both.
For large libraries, wp wpmc offload is faster and needs neither.
Failed items#
When a file cannot be offloaded, the plugin records the reason. Common reasons are a missing file on disk, a permission error from the provider or a network error.
You can see failed items in three places:
- Media > Library (list view): the row shows Offload failed with a Retry link. Hover over it to read the reason.
- Dashboard tab: the Bulk Offload card shows how many items failed. Open the list to read each reason, then click Retry all or Clear.
- WP-CLI:
wp wpmc failedlists each item with its error.wp wpmc offload --retry-failedretries them.
Clear only empties the list. The next bulk offload picks the items up again.
Deletion#
By default, deleting media in WordPress leaves the files in your bucket.
Turn on Delete from cloud when deleted in WP on the Settings tab to remove them too. The plugin then deletes every size of the attachment from the bucket and removes its record. This cannot be undone through the plugin.
If another attachment still uses the same file, for example a WPML or Polylang translation, the files stay in the bucket and only the deleted attachment’s record is removed. This needs WP Media Cloud 1.1.9 or newer.
Multisite networks#
On a multisite network, each subsite works on its own:
- Each subsite has its own settings, offload records and bulk offload queue. Bulk offloads on different subsites do not affect each other.
- A network admin sees every subsite’s progress and failed items on the WP Media Cloud: Network Overview page in Network Admin.
wp wpmc offload --networkoffloads every subsite from the command line.
Subsites can share one bucket when each keeps its files in its own folder: set Path prefix to sites/%site_id%. Without a prefix, subsites in one bucket would overwrite files with the same upload date and name, so give each its own bucket instead.
Constants in wp-config.php apply to every subsite, so they point all subsites at the same bucket. Use them only with define( 'WPMC_PATH_PREFIX', 'sites/%site_id%' );.