WordPress media_sideload_image Example: Import a Remote Image Safely

Last reviewed: April 27, 2026

Importing a remote image into the WordPress media library is a common requirement for feeds, migration tools, external catalogs, and content synchronization jobs. The mistake is assuming a remote URL can be treated like a local upload with no extra safeguards.

This guide shows how to use media_sideload_image() safely, including the required admin includes, error handling, and attachment ID retrieval for later use.

Load the media helpers outside wp-admin when needed

<?php
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/image.php';

The WordPress reference explicitly notes this requirement for non-admin contexts such as importer scripts, custom routes, or background jobs.

Sideload and request the attachment ID

$image_url     = 'https://example.com/images/report-cover.jpg';
$attachment_id = media_sideload_image( $image_url, $post_id, 'Imported report cover', 'id' );

if ( is_wp_error( $attachment_id ) ) {
	return $attachment_id;
}

Using the id return type is usually the most practical choice because later code can set featured images, store metadata, or render responsive attachment markup cleanly.

Set the featured image after import

set_post_thumbnail( $post_id, $attachment_id );

After sideloading succeeds, the attachment behaves like any other media library item.

Validate the source you are willing to trust

Sideloading a remote image is still a network trust decision. Restrict the source hosts if the importer should only consume known providers.

$host = wp_parse_url( $image_url, PHP_URL_HOST );

if ( ! in_array( $host, array( 'cdn.example.com', 'images.example.net' ), true ) ) {
	return new WP_Error( 'invalid_host', 'Remote image host is not allowed.' );
}

Production checklist

• Load the required admin media includes outside wp-admin contexts.
• Use the id return type when later code needs the attachment object.
• Handle WP_Error explicitly.
• Allowlist remote hosts when imports should be restricted.
• Attach the image to the correct post only after the sideload succeeds.
• Keep remote import workflows idempotent when the same content may sync twice.

Common mistakes

• Calling the function outside wp-admin without includes. The import path then breaks immediately.
• Using the default HTML return when an attachment ID is needed. That makes downstream media handling awkward.
• Trusting any remote host. Imports should come from known sources.
• Skipping error handling. Remote downloads fail more often than local uploads.
• Assuming the description is full attachment metadata. Keep title, alt, and other fields explicit when needed.

Related reading

If the imported attachment is later rendered in templates, pair this with the wp_get_attachment_image guide. If the post itself is created programmatically during the same sync, combine it with the wp_insert_post article.

References and further reading

• WordPress Code Reference: media_sideload_image()
• WordPress Code Reference: download_url()
• WordPress Code Reference: media_handle_sideload()