WooCommerce products use a featured image (main product image) and an optional product gallery. Import WP can download images from remote URLs, local paths, FTP, or reuse items already in the Media Library. See the WooCommerce importer.
Image imports are one of the most common WooCommerce support topics — especially remote URL downloads, galleries not attaching, and duplicate images on update.
Which section should I use?
| Section | Use for |
|---|---|
| Product Gallery | WooCommerce featured image + gallery (recommended for products) |
| Images & Attachments | Extra attachments, or featured image using the standard attachment UI |
For most product imports, map images in Product Gallery.
Note: Advanced → Is Featured is the WooCommerce “featured product” catalogue flag (starred product). It is not the featured image. Featured images are controlled by Is Featured? on an image/attachment row.
Example CSV
| Name | SKU | Price | Images | Image Title |
|---|---|---|---|---|
| Simple Product 1 | simple-one | 10.99 | https://example.com/a.webp, https://example.com/b.webp | Title A, Title B |
| Simple Product 2 | simple-two | 12.99 | https://example.com/c.webp | Title C |
Map the Product Gallery
- Open the Product Gallery section.
- Set Location to your images column (comma-separated URLs or paths).
- Choose the download / location method (Remote URL, Local filesystem, FTP, or Media Library search).
- Set Is Featured? = Yes so the first image becomes the main product image. Remaining images are added to the gallery.
- Optionally enable Enable Meta to map alt text and title.
Multiple images in one cell must be separated with a comma (or your configured delimiter). The same delimiter applies to matching meta columns (titles, alt text).
Featured image vs gallery
| Goal | Setting |
|---|---|
| First image = featured, rest = gallery | One Product Gallery row, Is Featured? = Yes, multiple comma-separated URLs |
| Featured only | One URL, Is Featured? = Yes |
| Gallery only (no featured change) | Map gallery images with Is Featured? = No |
| Featured via Images & Attachments | Use Images & Attachments with Is Featured? = Yes |
When a Product Gallery row has Is Featured? = Yes, that image is set as the featured image and included in the gallery ID list.
Image meta (alt text and title)
Enable Enable Meta on the gallery/attachment row, then map:
- Alt Text
- Title Text
Keep the number of meta values aligned with the number of image URLs when importing multiple images in one field.
Download behaviour and duplicates
Attachment rows include permissions / download options such as:
- Always download new files — creates a new Media Library item each run (can duplicate images)
- Search media library (hash / filename based) — reuses an existing attachment when possible
Recommendations:
- For scheduled updates of the same catalogue, prefer searching the Media Library so the same image is not downloaded repeatedly.
- If the same image URL is used on many products, Media Library search helps attach one file to multiple products instead of uploading copies.
- Soft-deleted / “Delete unused records” behaviour can remove media in some setups — test on staging before bulk-deleting products with media cleanup enabled.
Variation images
To set an image on a product variation:
- Import the variation row as Product Type
variation. - Map an image on that variation (Product Gallery or Images & Attachments with Is Featured? = Yes).
Parent gallery images are separate from per-variation images.
External image URLs (no Media Library upload)
By default Import WP downloads remote images into the WordPress Media Library (recommended for most stores).
If you need to store external URLs without uploading files (hotlinking / external featured image plugins), that usually requires an extra plugin or custom field mapping rather than the standard Product Gallery download flow. Confirm compatibility before purchase if this is a hard requirement.
Common problems
| Symptom | What to check |
|---|---|
| Images not importing | URL reachable from the server (SSL, firewall, 403/404), PHP timeout/memory |
| Images download but product has no image | Mapped to wrong section; Is Featured? not set; permissions blocking product_gallery |
| Only first image imports | Delimiter wrong (not comma); remaining URLs invalid |
| Duplicate images every update | Switch from “always download” to Media Library search |
| Gallery empty after update | Permissions exclude gallery fields on update; or empty image field clears data |
| Categories import but images don’t | Separate issues — fix image URLs first; see also taxonomy guide |
| “Unable to download” / cURL errors | Server cannot reach remote host; try downloading the URL from the server CLI |
Updated 2026-09-07