Docs

URL Replace tool

5 min readUpdated November 9, 2026

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:

StatusWhat it meansWhat to do
Will be switchedSafe to switchNothing
Not offloaded yetIn the Media Library, still on your server onlyClick Offload that media first in the preview, then scan again
Not in the Media LibraryA file on your server that WordPress does not track, such as an FTP upload or a plugin’s cache fileAdd 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 alreadyFix the link in the post
Recorded, but not found in the bucketThe record says offloaded, but the bucket does not have the fileUpload the file again, for example with Enable Media Replace; the image is already broken on the CDN
In a different bucket or providerOffloaded to a bucket you no longer useSwitch Settings back to that bucket, or contact support to move the files
Protected store fileA WooCommerce or Easy Digital Downloads product fileNothing: store downloads are handled by the store integrations
No local copy to switch back toBack to local only: the server copy is goneRestore 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#

URL Replace tool before a scan
  1. Back up your database.
  2. Finish the bulk offload, so as many files as possible can be switched.
  3. Try it on a staging copy first if you can.

Running URL Replace#

URL Replace scan results
Confirmation before URL Replace changes the database
  1. Go to Media Cloud > Migration and scroll to URL Replace.
  2. Choose Local URLs to CDN or CDN URLs back to local.
  3. Optionally turn on Also search plugin tables. Leave Check each file in the bucket first on unless the site is very large.
  4. Click Scan (preview). Nothing is changed while it scans.
  5. 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.
  6. 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#

URL Replace for 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.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only