How WP Media Cloud works

4 min readUpdated June 27, 2026

Understanding how WP Media Cloud works makes it easier to configure correctly, troubleshoot when something goes wrong, and know what to expect when you enable or disable individual features. This document explains what happens at each stage of the upload, delivery, and deletion process.

The upload process#

When a file is uploaded to WordPress through the media library, the WordPress admin, a front-end form, or any plugin that uses the WordPress media upload API, the following happens:

WordPress receives the file and saves it temporarily to wp-content/uploads in the standard year/month folder structure.
WordPress processes the file. For images this includes generating thumbnail sizes based on your registered image sizes.
WP Media Cloud intercepts after processing is complete. It uploads the original file and all generated thumbnail sizes to your configured cloud storage bucket.
WP Media Cloud updates the WordPress attachment record to store the cloud storage URL and path.
If local file removal is enabled, WP Media Cloud deletes the local copies from wp-content/uploads. If it is disabled, the local copies remain alongside the cloud copies.

From this point on, any part of WordPress that reads the attachment URL receives the cloud storage URL. This includes the block editor, page builders, custom fields, WooCommerce, and any plugin that uses wp_get_attachment_url() or wp_get_attachment_image_src().

URL rewriting#

WP Media Cloud does not modify your database to store cloud URLs permanently against every attachment. Instead it hooks into the WordPress attachment URL functions and rewrites the URL at the point of output. This means:

If you deactivate WP Media Cloud, WordPress falls back to the original local URL immediately. If local files were removed, those URLs will 404 until local files are restored or WP Media Cloud is reactivated.
Changing your storage provider or CDN configuration takes effect immediately for all future URL output, without needing to update the database.
URLs in post content that were saved as cloud URLs (rather than generated dynamically) are not automatically updated when configuration changes. This is what the URL Replace tool is for.

Existing media#

WP Media Cloud only offloads files automatically at the point of upload. Files that were uploaded before WP Media Cloud was installed remain on your server and are served from their local URL. To move existing files to cloud storage, run the bulk migration tool from WP Media Cloud > Tools > Bulk Migration.

The bulk migration tool uploads every file in your media library to your configured cloud storage bucket and updates each attachment record. It runs in the background with no item limits and can be paused and resumed.

CDN delivery#

If you configure a CDN in WP Media Cloud settings, the CDN hostname replaces the storage bucket hostname in all generated URLs. The file path within the bucket remains the same. WordPress requests the file from the CDN edge, and the CDN fetches it from the origin bucket on first request and caches it for subsequent requests.

WP Media Cloud does not manage CDN cache invalidation directly. If you replace a file in the media library and CDN caching causes the old version to persist, enabling file versioning appends a timestamp to filenames on upload, which forces the CDN to treat the new file as a different URL.

Deletion#

When a file is deleted from the WordPress media library, WP Media Cloud can optionally delete the corresponding file from cloud storage at the same time. This is controlled by the mirror deletion setting in WP Media Cloud > Settings.

Mirror deletion is permanent. Files deleted from cloud storage cannot be recovered through WP Media Cloud. If you need to retain files in cloud storage even after deleting them from WordPress, disable mirror deletion.

What WP Media Cloud does not do#

It does not offload theme files, plugin assets, or any file outside wp-content/uploads.
It does not modify your WordPress database schema.
It does not require changes to your theme, page builder, or any other plugin.
It does not affect how the WordPress media library looks or works in the admin.
It does not serve files itself. Files are served directly from your cloud storage bucket or CDN.