Frequently Asked Questions

The questions we’re asked most often about External Images, drawn from five years of support. For error messages and things that have stopped working, see the Troubleshooting guide, or ask us on Discord.

How does External Images actually work?

Instead of downloading images into your Media Library, External Images stores the remote URLs in postmeta and creates lightweight “fake” attachment entries in the database so that themes, plugins and WordPress core all behave as though the image is a normal local attachment. Those fake entries take no real disk space. This is why External Images works with almost every theme, plugin and feature (including the WooCommerce REST API) – the only things it can’t help are plugins that read image data directly from the database and reject anything not on your own domain.

Which field do I import my image URLs into?

This is the single most important thing to get right. Import into external_image_url – the public field, no leading underscore. Put your URLs in it separated by the pipe | character; the first URL is the featured image and the rest become gallery images. The same applies to variations, via the variation’s own external image area. Any import tool that can set postmeta works (WP All Import, WebToffee, WP Sheet Editor, or manual editing) – not just WP All Import.

The other fields, for reference – do not import into the underscore ones:

• external_image_url – the field you import to (public, pipe-separated).
• _external_image_url – private (leading underscore); a serialized array the plugin maintains internally. Never import into it. WP All Import sometimes suggests this one by mistake – that’s the most common cause of “the URL is saved but no image shows”.
• ei_converted – an internal flag; set it to 0 to force the plugin to re-read your URLs and rebuild the images (see the Troubleshooting guide).
• ei = 1 – the marker the plugin puts on its fake attachment posts.
• _ei_wcgallery – the private WooCommerce gallery array (maintained automatically).

You can freely mix products with and without external images: if an external image URL exists it overrides the local image; if not, the local image is used, and failing that the placeholder. Physically uploaded images take precedence over external ones. Full walkthrough: How to alter import jobs to import external images.

How do I set alt text, titles and captions?

Load them into three postmeta fields, in the same order as the URLs in external_image_url: external_image_alts, external_image_titles and external_image_captions. Don’t try to cram several alts into one field with pipes or commas. You can also edit these later from the Media (upload.php) editor. To force existing texts to re-map, change the relevant field and set ei_converted to 0. The text is passed through the WordPress translation system, so it works with Loco Translate / Polylang.

Where do I edit the image URL and gallery URLs in the editor?

In the Gutenberg editor the External Images boxes moved from directly under the Featured Image area to their own collapsible meta box at the bottom of the page. For WooCommerce products, you’ll find the external image and gallery fields in the product data area and beneath the gallery.

How do I reorder gallery images?

There’s no live drag-to-reorder yet. Clear the external_image_url field and re-enter the images in the order you want (pipe-separated). If do_action calls are enabled in your import, it detects the changed field and rebuilds automatically; otherwise set ei_converted to 0 as a failsafe.

Where should I host the images, and do I need a CDN?

Any publicly-reachable image URL works – a supplier/affiliate CDN, S3, DigitalOcean Spaces, BunnyCDN, Google Cloud Storage, or even a folder on your own server. The recommended setup is to host your images on a subdomain like images.yourdomain.com and put a CDN (Cloudflare, KeyCDN, BunnyCDN, Imgix) in front that resizes on the fly for each visitor’s screen – don’t resize on your own server, it wastes CPU. If your supplier images sit on a third-party domain and won’t cache at your CDN, set up CNAME records so each supplier maps under your domain (e.g. awin.yourdomain.com → the supplier host) and rewrite the URLs in your import to use it. External Images does not upload to S3/CDN for you – the images must already be hosted somewhere.

What does the “Proxy All Images” option do?

It serves external images through your own server: the first time an image is viewed it’s downloaded and cached to wp-content/uploads/external-images/, then served locally afterwards. It only caches images that are actually viewed. Trade-offs: the first load of a page is slower (your server fetches the images), it uses disk space, and it’s not ideal for archive pages with lots of images – it’s most useful for making a single page’s featured image appear to come from your own domain (helpful for SEO scrapers). There’s a Clear Cache button (the folder can be emptied any time – it just rebuilds on next view). If you cache proxied images at Cloudflare, add a Page Rule: URL contains ssl-proxy.php → Cache Everything.

How do I give external images a uniform size?

Use the CSS Crop (CSS image cropping) option on the settings page – it forces images to a fixed size in the browser. Alternatively the Photon resizer produces on-the-fly sized-and-cached images (it uses local storage as a cache), which is handy for affiliate-network images. The plugin can’t set real width/height without downloading images, so for PageSpeed’s “properly sized images” a CDN that resizes for the screen is the cleanest fix. If your theme’s own gallery CSS fights the crop, disable Photon resizing and rely on CSS Crop.

Can I show a fallback image when a URL is broken?

Yes – there’s a default/placeholder image option in Settings > External Images, and you can set a custom fallback image URL. When an image fails to load, the plugin’s onerror handler swaps in the fallback (by default external-images/assets/img/coming-soon.jpg). If you’d rather show nothing, add a little custom JS to remove that onerror handler. Seeing the fallback appear at all means the underlying image URL is failing to load.

Does it work with the WooCommerce REST API?

Yes, perfectly. Because External Images fakes attachment entries in the database, the images appear in the REST API just like local ones. To test, create a key under WooCommerce > Settings > Advanced > REST API, then load https://yourdomain.com/wp-json/wc/v3/products/{product_id}?consumer_key={key}&consumer_secret={secret} and check the images array. This same fake-attachment approach is why it works with almost every plugin and theme.

How do external images appear to Google, Facebook and Twitter, and is it bad for SEO?

The plugin sets the social meta tags (og:image, twitter:image) using the first URL from external_image_url, or the featured image, or the first image in your content. The <img> HTML with your alt text is still on the page for Google to read (check via View Source, not Inspect Element), so it’s SEO-neutral to positive – and a faster, lighter site helps SEO. If you use the proxy option, the images even appear to come from your own domain, so there’s no difference from local images. To test sharing previews, use Facebook’s Sharing Debugger (Facebook caches for 48h+) and Twitter’s card validator. We set the image width/height in the tags to satisfy the scrapers, and proxy the URL through your domain so future platform checks can’t penalise a third-party host.

A specific widget, shortcode or carousel isn’t showing external images

The usual cause is that the widget, shortcode or theme has its own image resizing/cropping or gallery option enabled (as opposed to WordPress’s own). External Images can’t be resized by those custom services – it crops with CSS – so set the resizing option to No / default. For example, the WooCommerce Product Carousel plugin has an “Image Resizing & Cropping” toggle that must be off. If you find a widget or shortcode that still won’t work after checking for resizing/gallery/styling options, tell us on Discord and we’ll write a fix for it.

Is my theme compatible?

External Images works with 95%+ of themes by overriding the WordPress functions that fetch thumbnails and featured images. Confirmed-compatible themes include Rehub, Storefront, Woodmart, Flatsome, Shoptimizer, Themify Ultra and many more, plus property themes like Houzez and RealHomes (some need a display-option tweak – see Troubleshooting). If images don’t show in a shop archive or product page: make sure the theme is WooCommerce-compatible, and disable any theme “product gallery” option (External Images ships its own). If a theme uses a completely non-standard admin (some directory themes don’t use standard WordPress hooks so the meta boxes can’t be injected), it may need the theme author to add hooks – contact us and we’ll find a solution.

Is it compatible with offload-media plugins, variation galleries and page builders?

Yes – because it uses its own postmeta fields it coexists with WP Offload Media, HappyFiles and similar. Variation image gallery plugins (woo-variation-gallery, woo-product-variation-gallery, WooCommerce Additional Variation Images) are supported, and there are wp-config constants to tune them (see below). It works with page builders (Oxygen, Elementor, Divi) and grid plugins like WP Grid Builder and Jet Engine galleries. For any custom-gallery theme or plugin, the method is the same: leave the theme’s own image field empty and load your URLs, pipe-separated, into the external_image_url postmeta field.

How do I migrate external images to another site, or translate with WPML?

When moving between sites, export the external_image_url postmeta field (not the underscore _external_image_url, whose attachment IDs won’t match on the destination). It’s a plain postmeta field, so WP All Export can export it even though ACF’s own export list won’t show it. For WPML translations that lose the images, go to WPML’s Custom Fields settings, click “Show system fields” (it hides underscore-prefixed fields like _ei_wcgallery by default), and set the External Images fields to “Copy once” so translations keep the images.

How do I get an external image URL in my own PHP code?

The standard wp_get_attachment_url() functions can return empty in admin contexts (order emails, custom admin columns) because many of the plugin’s filters are disabled on admin screens. Use the plugin’s own resolver, passing the post/product ID (not an attachment ID):

global $ei;
$image_url = $ei->common->ei_replace_attachment_image_url( '', $product->get_id() );

If a product might have no external image (which can throw a stripos() error on the line above), use the array form instead:

$img_array = $ei->admin->ei_get_image_meta( $product->get_id() );
$img = $img_array['img_url'];

Does it work with caching and preload?

Yes – it works with WP Rocket, WP Super Cache, LiteSpeed and Cloudflare (including APO). The one thing to avoid is a cache plugin’s “preload images” option, which breaks external images; preloading pages and categories is fine. If you import with Cloudflare, see the Cloudflare section of the Troubleshooting guide.

Which wp-config.php constants can I use?

• define('EI_ADD_FEATURED_IMAGE_TO_GALLERY', true); – add the featured image into the gallery if your theme excludes it (remove it if you get a doubled image).
• define('EI_DISABLE_VARIATION_JS', true); – disable External Images’ variation JavaScript when it clashes with a theme or swatch plugin’s own gallery JS.
• define('EI_VARIATION_GALLERY_WRAPPER_CSS', '.woocommerce-product-gallery'); – point at a custom variation-gallery container for themes with a non-standard wrapper.
• define('EI_SHOW_VARIATION_IMAGES_IN_MAIN_GALLERY', false); and define('EI_GRAB_PARENT_GALLERY_IF_NO_GALLERY', true); – restore older variation-gallery behaviours if you relied on them.

Why do external images show in the Media Library, and can I hide them?

Those are the spoofed/fake attachment entries the plugin creates for compatibility – they take no disk space, and the same image URL used on many products will appear multiple times without using any storage. There’s a Show/Hide External Images dropdown on the Media Library (show all / only internal / only external). To bulk-remove orphaned ones after deleting products, see the cleanup section of the Troubleshooting guide.

What happens when my licence expires?

Nothing stops working. External Images is GPL, so all features keep functioning after a licence expires – you only lose access to automatic updates and support. If a new key isn’t accepted right after purchase, flush your object cache; the licence check is cached server-side for up to about 4 hours.

Got an error rather than a question? See the Troubleshooting guide, or ask on Discord.