URL Replace tool
URL Replace rewrites media addresses saved in your database, either from your site’s uploads URL to your CDN, or back. You usually do not need it: URL rewriting already serves offloaded files from your CDN as pages load. Use URL Replace to make the change permanent, for example after a migration, or before you stop using WP Media Cloud.
Beta. This tool writes directly to your database. Take a full database backup and try it on a staging copy first.
How it decides what to change#
URL Replace checks every file on its own and only switches addresses that will keep working:
- To the CDN: only when WP Media Cloud has a record of the file in your current bucket. With Check each file in the bucket first on (the default), the file is also confirmed in the bucket with a live request.
- Back to local: only when the local file exists on your server. This also repairs CDN links that versions before 1.2.1 wrote for files that were never offloaded.
Anything else keeps its address and is listed in the preview with the reason:
| Status | What it means | What to do |
|---|---|---|
| Will be switched | Safe to switch | Nothing |
| Not offloaded yet | In the Media Library, still on your server only | Click Offload that media first in the preview, then scan again |
| Not in the Media Library | A file on your server that WordPress does not track, such as an FTP upload or a plugin’s cache file | Add it to the Media Library if it should be offloaded |
| Missing (no local file and no cloud record) | The file is nowhere: a broken link already | Fix the link in the post |
| Recorded, but not found in the bucket | The record says offloaded, but the bucket does not have the file | Upload the file again, for example with Enable Media Replace; the image is already broken on the CDN |
| In a different bucket or provider | Offloaded to a bucket you no longer use | Switch Settings back to that bucket, or contact support to move the files |
| Protected store file | A WooCommerce or Easy Digital Downloads product file | Nothing: store downloads are handled by the store integrations |
| No local copy to switch back to | Back to local only: the server copy is gone | Restore the file first (see below) |
Where it looks#
Always searched:
- Posts, pages and custom post types: content and excerpt (revisions are skipped)
- Custom fields (post meta), including page builder data
- Settings (options), including theme settings such as Kadence Customizer backgrounds
- Term meta and category and tag descriptions
- Comments and comment meta
- User profile fields
With Also search plugin tables on, every other table with your site’s prefix is searched too, for example block CSS tables, form entries and slider data. Tables without a single-column primary key are skipped.
Never changed: WordPress core URL settings, transients, user accounts, sessions, WP Media Cloud’s own data, and WooCommerce and Easy Digital Downloads product file lists.
Which URL forms it finds#
Every way an address can be saved: https://, http:// and //, with or without www, each written plainly, JSON-escaped (https:\/\/, used by page builders) or URL-encoded (https%3A%2F%2F). The new address is written in the same form as the old one.
How saved data is protected#
- Serialized data is unpacked, changed and packed again, so its stored lengths stay correct.
- Data that cannot be read safely (damaged serialized values, or values holding a plugin’s own objects) is never changed. The preview counts these.
- Values too long for their column are skipped instead of being cut short.
- Every saved value is read back. If the database did not store exactly the new value, the old one is put back.
- Undo data is saved first. Each value’s old content is stored before it changes.
Before you run it#

- Back up your database.
- Finish the bulk offload, so as many files as possible can be switched.
- Try it on a staging copy first if you can.
Running URL Replace#


- Go to Media Cloud > Migration and scroll to URL Replace.
- Choose Local URLs to CDN or CDN URLs back to local.
- Optionally turn on Also search plugin tables. Leave Check each file in the bucket first on unless the site is very large.
- Click Scan (preview). Nothing is changed while it scans.
- Review the preview: the number of files that can be switched, the status of every file and where each one is used, with links to edit the posts.
- Click Switch N files, then Yes, switch them. Keep the tab open until it finishes.
If the tab closes during a run, open the page again and it continues. A run that has not moved for 5 minutes can be cleared with a new scan; everything it changed can still be undone.
One post or page#

The One Post or Page card applies the same rules to a single post and its custom fields. Enter the post ID and click Switch to CDN or Back to local. The result lists any files that were kept, and the change can be undone like a full run.
Undo#
After a run, the URL Replace card shows Last change with an Undo button. Undo puts back the old value of everything the run changed.
A value edited after the run is not overwritten; it stays as it is, and its old value stays saved. Delete undo data removes all saved old values; after that, earlier runs cannot be undone.
From the command line#
wp wpmc url-replace --dry-run
wp wpmc url-replace --all-tables
wp wpmc url-replace --to=local
wp wpmc url-replace --post=42
wp wpmc url-replace-undo --dry-run shows the preview counts only. --skip-check skips the bucket check. --yes skips the confirmation. The command prints a run ID; wp wpmc url-replace-undo --run=<id> undoes that run.
Checking the result#
Open a few pages, including any with page builder layouts, widgets or theme backgrounds, and check images load. In your browser’s developer tools, the image addresses now start with your CDN hostname.