Restore Featured Images from WXR

A small WordPress admin tool that restores featured-image relationships after a WordPress migration.

It reads the original WordPress WXR/XML export, finds each post's old _thumbnail_id, matches that old attachment to an image already registered in the current Media Library, and then restores the featured image with set_post_thumbnail().

What this tool does

• Reads the original WordPress export file.
• Builds a map of old attachment IDs to their original paths in wp-content/uploads.
• Matches imported posts by old ID, slug, date, and title.
• Matches local Media Library images by _wp_attached_file.
• Restores the original featured image for each post.
• Does not overwrite a valid featured image that is already assigned.
• Shows a summary of restored, missing, and unmatched records.

What this tool does not do

• It does not download image files from the old website.
• It does not automatically register files that exist only on the server.
• It does not restore images that are missing from the current Media Library.
• It currently targets the standard WordPress post post type.

Before running this tool, the images must already exist in wp-content/uploads and must be registered in Media → Library.

Requirements

• WordPress 5.8 or newer
• PHP 7.4 or newer
• PHP XMLReader extension
• PHP SimpleXML extension
• Administrator access
• The original WordPress WXR/XML export file

Important safety step

Create a full database backup before running the restoration.

This tool updates _thumbnail_id relationships in the WordPress database.

Installation

Option 1: Install as a plugin

1. Download restore-featured-images-from-wxr.zip.
2. In WordPress, open: Plugins → Add New Plugin → Upload Plugin
3. Upload the ZIP file.
4. Click Install Now.
5. Activate Restore Featured Images from WXR.

Option 2: Install manually

1. Create this folder:

   wp-content/plugins/restore-featured-images-from-wxr/

2. Copy restore-featured-images-from-wxr.php into that folder.

3. Open Plugins in WordPress.

4. Activate Restore Featured Images from WXR.

Prepare the XML file

1. On the old WordPress website, open:

   Tools → Export

2. Export All content or at least the posts and their attachment records.

3. Rename the downloaded export file to:

   wordpress-export.xml

4. Upload it to the WordPress root directory of the new website, beside wp-config.php.

Typical cPanel path:

/public_html/wordpress-export.xml

The plugin expects this exact filename:

wordpress-export.xml

Prepare the Media Library

The image files must already be available on the new website.

The final server structure should look similar to:

wp-content/uploads/2023/01/example.jpg
wp-content/uploads/2024/06/example.jpg

The files must also appear in:

WordPress Dashboard → Media → Library

Copying files with FTP or cPanel does not automatically register them in the Media Library. Use a media-registration tool first when necessary.

Run the restoration

1. Log in as a WordPress administrator.

2. Open:

   Tools → Restore Featured Images

3. Confirm that the page displays:

   The XML file was found and is ready.

4. Click Restore Featured Images once.

5. Keep the page open until the results table appears.

6. Review these values:

   • Featured-image records found
   • Featured images restored
   • Posts already having an image
   • Posts not found
   • Old attachment records missing
   • Local Media Library images missing
   • Failed image assignments

Understanding missing media

A result such as:

Media not found: 2023/01/example-700x400.jpg

means that the original XML references that exact path, but WordPress cannot find a registered Media Library attachment with the same _wp_attached_file value.

Check all of the following:

• The file exists in the correct wp-content/uploads/YYYY/MM/ folder.
• The filename matches exactly, including uppercase/lowercase letters.
• The image is registered in Media → Library.
• The Media Library attachment stores the correct relative file path.

After fixing the missing media record, run the restoration again. Existing valid featured images will not be overwritten.

After completion

1. Check several posts manually.
2. Confirm that their Featured Image fields are correct.
3. Deactivate and remove the plugin when it is no longer needed.
4. Delete the XML file from the public server:

/public_html/wordpress-export.xml

Keeping migration exports in a public web directory longer than necessary is not recommended.

Matching logic

Posts are matched in this order:

1. Original WordPress post ID, when still valid
2. Slug and publication date
3. Slug only
4. Cleaned title and publication date
5. Cleaned title only

Attachments are matched by the _wp_attached_file value. A filename-only fallback is used only when exactly one matching image exists.

The title fallback also removes common qTranslate markers such as:

[:en]Title[:]

Recommended workflow

1. Export content from the old website.
2. Import posts into the new website.
3. Copy the original uploads folders.
4. Register copied images in the new Media Library.
5. Run this featured-image restoration tool.
6. Review missing records.
7. Remove the plugin and XML file after verification.

License

GPL-2.0-or-later