URL Replace tool

4 min readUpdated June 28, 2026

Note: This feature is in beta

The URL Replace tool scans your WordPress database for media URLs and rewrites them to match your current WP Media Cloud configuration. It is a beta feature designed for situations where dynamic URL rewriting is not sufficient — typically when a page builder, plugin, or the classic editor has saved a full URL string directly into the database rather than storing an attachment ID.

What the URL Replace tool does#

WP Media Cloud rewrites attachment URLs dynamically at the point of output by hooking into WordPress’s attachment functions. This handles the vast majority of cases. However, some situations leave old URLs written directly into your database as plain text strings that are never passed through WordPress’s attachment functions:

Page builders that save the full image URL into postmeta or post content rather than storing only the attachment ID
Classic editor content where images were inserted as HTML with hardcoded src URLs
Custom field values stored as plain URL strings rather than attachment IDs
Switching storage providers or CDN configurations, which changes the hostname in all URLs
Changing your path prefix, which changes the path in all URLs
Migrating from another offload plugin that stored URLs in a different format

The URL Replace tool performs a database find-and-replace across these stored values, locating all instances of your old URL pattern and replacing them with the correct cloud or CDN URL.

What the tool covers#

The URL Replace tool scans the following database tables:

wp_posts — post content and post excerpt
wp_postmeta — all postmeta values
wp_options — widget data, theme customiser settings, and other option values where page builders and plugins store their data

The tool handles all of the following URL formats it may encounter in these tables:

Plain URL strings
PHP-serialized data (common in postmeta stored by ACF, Meta Box, and page builders)
JSON-escaped forward slashes
URL-encoded variants

This makes it compatible with all major page builders including Bricks Builder, Elementor, and ACF custom fields without requiring any additional steps.

Beta status#

The URL Replace tool is currently in beta. It works correctly in standard WordPress configurations but has not been tested against every possible database structure or third-party plugin. Always take a full database backup before running it and test on staging before running on production.

Before running the URL Replace tool#

Take a full database backup. The URL Replace tool modifies your database directly. A backup is the only way to recover if something goes wrong.
Run the bulk migration tool first. The URL Replace tool rewrites URLs but does not move files. If files have not been offloaded, replacing their URLs will result in broken links. Confirm all files are in cloud storage before running the replace tool.
Test on staging first. Run the full process on a staging copy of your site before touching production. Confirm the results look correct before proceeding on production.
Confirm your current configuration is correct. The tool rewrites URLs to match your current storage and CDN settings. If your settings are wrong, the replaced URLs will be wrong.

Running the URL Replace tool#

Go to WP Media Cloud > Tools > URL Replace. The tool shows a preview of the URL pattern it will search for and the URL pattern it will replace it with, based on your current storage and CDN configuration. Review the preview carefully before proceeding.

Click Run URL Replace to start the full replacement across all three tables. The tool processes rows in batches as a background operation and displays progress as it runs.

For targeted fixes on a single post, use the per-post replace option, which lets you run the replacement against a specific post ID rather than the entire database. This is useful when testing the tool or when only a small number of posts need updating.

Reverting to local URLs#

The URL Replace tool includes a full revert option. If you run the replacement and the results are not what you expected, you can revert all replaced URLs back to local URLs at any time from the same tool interface. This makes the tool safe to experiment with, provided you have run it on staging first and understand what the revert will do.

Verifying the results#

After the tool completes, spot-check several pages on your site to confirm images are loading correctly. Check any custom field values that store image URLs, widget areas, and any content built with page builders. If images are not loading, check the URL being requested in the browser’s network tab and compare it to what exists in your bucket.

Using WP-CLI as an alternative#

For advanced users who need to cover custom database tables not included in the URL Replace tool, WP-CLI provides a comprehensive search and replace across all tables:

wp search-replace 'https://old-url.com' 'https://new-bucket-url.com' --all-tables

Always run with --dry-run first to preview changes before committing:

wp search-replace 'https://old-url.com' 'https://new-bucket-url.com' --all-tables --dry-run