Delayed Image Import: what happens to your images on each import
Delayed Image Import takes the featured and gallery image downloads out of a Super Speedy Imports run. The import writes the image URLs to the product instead of fetching the files, the product goes live straight away showing the supplier’s image, and a background cron job downloads the images afterwards at a pace the supplier’s server tolerates. This article describes exactly what each import writes, what the visitor sees at each point, and what happens when you import again with the same or a changed image URL. Every statement here was checked on a test site with ten products imported repeatedly, with the images uploaded by Super Speedy Imports, by Delayed Image Import and by hand.
Available since Delayed Image Import 2.30.1.
When to use it
Use Delayed Image Import when the image download is the slow or fragile part of your import: a supplier host that rate-limits or blocks bursts of requests, thousands of images per run, or an import that keeps reporting failed downloads and timeouts. Products and prices land in seconds; the images follow in the background.
If your images come from a fast host you control and the import completes comfortably, you do not need it. Super Speedy Imports downloads each distinct image once, records it in its own lookup table, and reuses it on later runs.
- Supplier image servers that throttle or block bursts of downloads
- Catalogues with thousands of images per import
- Imports where “failed image download attempts” dominate the history
Set-up
Install and activate Delayed Image Import alongside Super Speedy Imports. Nothing else is required: the import configuration screen gains a “Defer image downloads” checkbox in the Image options section, ticked by default while Delayed Image Import is active, and its background cron is switched on by default. Map your featured image and gallery columns exactly as you would without it.
Untick “Defer image downloads” on an import if you want that particular import to download its images itself, the way it would without Delayed Image Import.
What one import writes
With the checkbox ticked, the image stages of the import do no downloading at all. The import log shows the upload stage processing zero remote images. For every product in the file, the import writes the image URL from your column into the product’s delayed_image_url meta (and gallery URLs into delayed_gallery_image_urls), along with any alt, title, caption and description columns you mapped. That is the whole hand-off.
From that moment two things are true at once:
- On the shop, a product with no featured image of its own shows the supplier’s image directly from the supplier’s URL (a hot-link). Nothing is downloaded to do this, so the product is presentable the moment the import finishes.
- In the background, the cron job works through every product carrying a
delayed_image_url, downloads the file, adds it to the Media Library as a normal attachment, sets it as the product’s featured image, copies any alt, title, caption and description across, and removes thedelayed_image_urlmeta. Once that has happened the product is indistinguishable from one whose image was uploaded by hand.
The cron runs every minute by default and takes up to 100 images per tick, rotating across supplier domains so no single host is hammered. Each URL that fails is retried with a longer timeout and a longer wait each time, up to a ceiling, after which it is listed under Media > Delayed Images > Failed with the reason, where it can be retried or dismissed.
Importing again with the same image URLs
Every run of the import writes the URL to delayed_image_url again, whether or not the product has an image. The cron then checks, cheapest test first, whether the site holds that image before it downloads anything, and it never creates a second copy of an image the site has:
- An attachment stamped with the URL. Every image Delayed Image Import downloads or recognises carries its source URL in the
sspdii_original_image_urlattachment field. A match is one database query and no download. This is the steady state for every image the plugin has handled once. - An image Super Speedy Imports downloaded. Super Speedy Imports records every image it downloads against its URL in its own lookup table. Delayed Image Import reads that table, reuses the attachment, and stamps it. A store that imported with Super Speedy Imports and then switches on Delayed Image Import downloads nothing.
- An image put there by anything else. For an image uploaded by hand, by WP All Import or by any other tool, nothing records where it came from, so the plugin downloads the file once and compares its contents, as a hash, with the product’s own featured and gallery images and with any image in the Media Library whose filename matches the URL’s. Identical contents mean the download is discarded, the existing attachment is reused and stamped, and no new file is created. The filename and the URL only narrow the candidates; the contents decide.
In all three cases the product keeps its featured image, the Media Library gains nothing, and the shop keeps showing the image throughout. The only cost of switching an existing store over is the one-off download in case 3, which runs through the plugin’s usual throttle and retry ladder.
Delayed Image Import treats the contents of an image as its identity, and a URL only as a pointer to it. A supplier that keeps the URL but replaces the picture behind it is not noticed, because the URL is stamped on the attachment the site has. A supplier that changes the URL is handled as a new image, described next.
Importing again with a changed image URL
A changed URL in your file is treated as a new image. The import writes the new URL to delayed_image_url; the product keeps showing its current featured image until the cron reaches it; the cron downloads the new file and, if its contents match an image the site has (the same picture republished under a new name), reuses that attachment; otherwise it adds the file to the Media Library and sets it as the featured image with the alt and title from the new row.
The previous image is not deleted. It stays in the Media Library, still attached to the product, but not the featured image. Gallery images follow the feed the same way: once every gallery URL in the row has been downloaded, the product gallery is made equal to the feed’s list in the feed’s order, so an image whose URL left the feed leaves the gallery, and its attachment stays in the Media Library. A catalogue whose supplier changes image URLs on every feed will accumulate one attachment per change, so review the Media Library from time to time if that applies to you, or use a media clean-up plugin to remove attachments that are not a featured or gallery image.
Checking progress
- Media > Delayed Images lists every product still waiting, everything loaded, and everything that has failed with its reason and attempt count. Retry and dismiss act per URL.
- WP-CLI:
wp dii statusprints pending, loaded and failed counts with the cron heartbeat and throughput;wp dii load-featuredandwp dii load-alldrain the queue immediately from the command line instead of waiting for cron;wp dii pauseandwp dii resumestop and start the background job. - On a product, the presence of
delayed_image_urlin its custom fields means the image is still queued; once it is gone, the featured image is local.
Settings worth knowing
| Setting | Default | What it does |
|---|---|---|
| Background hydration cron | on | Runs the download job on a schedule |
| Tick interval | 1 minute | How often the job runs |
| Batch size per tick | 100 | Images attempted per run; lower it for a supplier that blocks bursts |
| Max consecutive same-domain | 1 | How many images in a row may come from one host before rotating |
| Force HTTPS | on | Rewrites http:// image URLs to https:// before downloading |
| Cooldown seconds | 60 | Base wait after a failure; multiplied by the number of failures so far |
A supplier that rate-limits is best served by a smaller batch and a longer interval: the total time to finish is longer, but every attempt succeeds instead of most of them timing out.
Frequently asked questions
Do I have to do anything each time I import?
No. Run the import as normal with “Defer image downloads” ticked. Queueing, downloading, retrying and setting the featured image are all automatic.
Does the downloaded image become a normal Media Library image?
Yes. It is a standard attachment with the usual thumbnail sizes, set as the product’s featured image, and it stays if you later deactivate Delayed Image Import.
If a product’s image URL changes in a later feed, is the image updated?
Yes. The new image is downloaded on the next cron pass and becomes the featured image. The old attachment is kept in the Media Library, not deleted.
What does a visitor see while an image is still queued?
A product that has never had a featured image shows the supplier’s image hot-linked from the supplier’s URL. A product that has a featured image keeps showing it until the new one is downloaded.
I edited a product image in WordPress. Will the next import overwrite it?
No. An attachment keeps its stamp when its file is edited, optimised or replaced under the same attachment, so while the feed keeps the same URL the product keeps the edited image. A changed URL in the feed replaces it, as any change does.
My images were uploaded before I installed either plugin. Will they be downloaded again?
Once, to compare their contents, and only for images neither plugin recorded. Nothing is added to the Media Library when the contents match, and after that first comparison the image is stamped and never fetched again for that URL.
Can I switch it off for one import?
Yes. Untick “Defer image downloads” on that import’s configuration and Super Speedy Imports downloads the images itself during the run.
Further reading
Written for Super Speedy Imports 2.99.19.
Comments