WooCommerce solution guide
Bulk upload WooCommerce product images by SKU, product ID, or slug
Prepare files around a stable product identifier, review each match, and test a small batch before changing a catalogue. BL Bulk Product Image Uploader for WooCommerce is built for controlled image assignment - not for guessing which image belongs to which product.
When supplier images, a migration, or a catalogue refresh leave you with hundreds of files, opening WooCommerce products one at a time is slow and error-prone. A bulk workflow can help when filenames reliably relate to the products that already exist in WooCommerce. The safe sequence is simple: choose one identifier, name a small test set, review every proposed match, verify the storefront result, then expand.
Direct answer
To bulk upload product images in WooCommerce, match each image filename to an existing SKU, WooCommerce product ID, or product slug. Use an optional numeric suffix to control the gallery position: IDENTIFIER.0.jpg, IDENTIFIER.1.jpg, and so on. BL Bulk Product Image Uploader then lets you review matches, correct a row manually, upload the file to the WordPress Media Library, and link it to the matched product, parent product, or variation.
Important current WooCommerce limitation: do not use Overwrite for a multi-image replacement batch. In the current Woo extension, the gallery is cleared for each file processed, so only the last file for that product remains in the gallery. Use Overwrite only for a carefully tested, one-image gallery replacement. For a multi-image gallery, leave Overwrite off and verify the resulting order on one product first.
Start with WooCommerce’s native option when the change is small
For a one-off product update, WooCommerce already lets a merchant set a main Product Image and add, re-order, or remove gallery images from the product editor. That is often the best route for a handful of products. WooCommerce documents that the main Product Image and Product Gallery are managed when adding or editing a product, and gallery images can be reordered by drag and drop. Read WooCommerce’s product-image and gallery guidance.
| Merchant situation | Best starting route | Why |
|---|---|---|
| One product needs one image changed | WooCommerce product editor | The native Product Image / Product Gallery controls are direct and easy to verify. |
| A few products need manual gallery edits | WooCommerce product editor | Use the native gallery UI when a repeatable filename workflow is unnecessary. |
| Many prepared supplier files map to existing products | BL Bulk Product Image Uploader | Match by SKU, product ID, or slug, review results, then process a controlled batch. |
| Individual variations need different primary images | Match a variation by its own SKU or variation ID | The app can assign the uploaded file to that variation’s image field. |
| Variation-related images should appear in the parent gallery | Match the variation, then enable Upload to parent product | This places the file in the shared parent product gallery instead of the variation image slot. |
Prepare filenames before opening the uploader
Choose one matching method for the batch. Mixing SKU files, product-ID files, and slug files in the same run makes review harder and increases the chance of attaching an image to the wrong record. The uploader accepts the identifier by itself, or an identifier followed by a numeric gallery position.
| Match method | Filename examples | Use it when |
|---|---|---|
| SKU | TSHIRT-001.jpgTSHIRT-001.1.jpg | Every target product or variation has a stable, unique SKU. |
| Product ID | 125.jpg125.2.jpg | Your source system already uses the WooCommerce / WordPress product ID. |
| Slug | blue-tshirt.jpgblue-tshirt.1.jpg | Your image library is named after the product URL slug. |
The filename pattern is IDENTIFIER.SORT_POSITION.extension. If there is no numeric suffix, the uploader treats the position as 0. For an ordered gallery, use a consistent set such as TSHIRT-001.0.jpg, TSHIRT-001.1.jpg, and TSHIRT-001.2.jpg. The order controls the gallery placement; it does not by itself decide the final featured image.
File checks before upload
The current WooCommerce uploader accepts JPG/JPEG, PNG, GIF, and WEBP through its browser queue, with a current 10 MB client-side file limit. WordPress server settings and security plugins can still reject a file, so a file that passes the queue is not a promise that every hosting setup will accept it.
Before a large run, keep the original image folder and export or back up the affected products. WooCommerce recommends retaining offline image copies in case an image is changed incorrectly and needs to be restored. See the native image-management documentation.
A controlled WooCommerce bulk-upload workflow
- Open WooCommerce → Bulk Image Uploader after installing and activating the extension.
- Choose SKU, Product ID, or Slug. Make sure that choice matches the filenames in the queue.
- Add a small test group of images. Each queued file shows its parsed identifier and sort position; edit either field if the filename needs correction.
- Select Match All. Review the product name on every matched row. A no-match row can be corrected and re-matched, or assigned through the product search picker.
- Decide whether each file belongs in a normal product gallery, a variation’s own image field, or the parent product gallery.
- Leave Overwrite off for a multi-image gallery. Enable Set as featured image only for the single file intended to become the final main thumbnail.
- Upload the test group, inspect the affected products in WooCommerce, then check the published product page on desktop and mobile.
- Only after the test is correct should you process the remaining catalogue. Review the final summary for linked and failed files.
How simple products, parent products, and variations differ
WooCommerce separates a parent product’s gallery from an individual variation’s image. A simple product or parent variable product can receive ordered gallery images. A variation matched by its own SKU or numeric variation ID can receive its own primary image. If the image should instead join the parent product’s main gallery, use Upload to parent product.
| Target | How to match | Result in the current extension | Check after upload |
|---|---|---|---|
| Simple product | Its SKU, product ID, or slug | File is linked into the product gallery at the selected position. | Main product page, gallery order, and optional featured image. |
| Parent variable product | Parent SKU, product ID, or slug | File is linked to the shared parent gallery. | Parent product gallery and how it appears before a shopper selects a variation. |
| Individual variation | That variation’s own SKU or variation ID | By default, the file is written to the variation’s individual image field. | Select that variation on the product page and confirm its expected primary image. |
| Variation routed to parent | Variation SKU or ID, plus Upload to parent product | File is added to the parent product’s gallery instead of the variation image field. | Parent gallery order; confirm the variation still has the intended separate image behavior. |
WooCommerce itself documents that each variation can have its own image. If a store uses the newer experimental Variation Gallery feature or a third-party variation-gallery plugin, test this workflow on staging or on a low-risk product first; those configurations can have their own image-storage and gallery behavior. Read WooCommerce’s current variable-product documentation.
Gallery position and featured image are separate decisions
A sort position controls where a normal product-gallery attachment is inserted. Set as featured image is different: it sets the product’s main image. If you enable that setting for several files that map to the same simple or parent product, the last processed file becomes the final featured image. For a variation, the normal variation upload path already assigns that variation’s image; the parent featured image is not automatically changed by that path.
A reliable practical pattern is to upload the intended main thumbnail as one clearly named file, test it, then add the remaining gallery files with featured-image assignment disabled. Do not assume that position 0 alone makes a file the featured image.
Use Overwrite with a narrow, controlled scope
Overwrite is the highest-risk setting because it changes existing gallery data. The current WooCommerce implementation clears the standard product gallery before each uploaded file is linked. This has two practical consequences:
- For a single-image gallery replacement, Overwrite can be used after testing a backed-up product.
- For multiple images mapped to the same product, leave Overwrite disabled. Enabling it causes each incoming file to clear the prior gallery state, leaving only the last processed file in that product’s gallery.
Overwrite does not clear the product featured image on its own. The featured image changes only when the separate Set as featured image option is used. The safest way to replace a multi-image gallery today is to back up the original images, remove or replace the gallery through WooCommerce’s native product editor, or perform a carefully tested additive upload with Overwrite off and then review the gallery.
Troubleshooting
An image does not match any product
Confirm that the selected method matches the filename. For SKU batches, check whether the product or variation actually has that SKU. For IDs, use the numeric WooCommerce / WordPress product ID - not an internal supplier ID. For slug matching, check the current product slug. Then use the product search picker to find the intended product by name, SKU, ID, or slug and correct the queued row before uploading.
The image is attached to the wrong variation or parent
Check whether the identifier belongs to a parent product or a specific variation. A variation route is appropriate only when the variation’s own image should change. If the image belongs in the common product gallery, route it to the parent product. Verify the storefront after selecting the variation because themes and variation-gallery features can render images differently.
The gallery order is not what I expected
Check the numeric suffix in the filename and the order value shown in the queue. Use distinct ascending positions for images on the same product. Remember that a featured image is controlled separately; changing a gallery position does not select a new main product thumbnail.
Only one image remained after an overwrite batch
This is the current multi-image Overwrite limitation. Restore the product from the original image files or backup as appropriate, then rerun the gallery addition with Overwrite disabled. Test the corrected workflow on one product before continuing.
An upload failed
The uploader retries a failed file up to two times before reporting it as failed. Check that the source file is a supported format, is no more than 10 MB, and can be uploaded through the WordPress Media Library. Review the individual error row rather than rerunning every file in the batch. Hosting upload limits, security rules, or a temporary media-library failure can still require a targeted retry.
Frequently asked questions
Can I bulk upload WooCommerce product images by SKU?
Yes. Choose SKU matching and name each file with the exact product or variation SKU. Review the proposed match before upload, especially if a SKU could be shared, incomplete, or incorrectly entered.
Can I match images by WooCommerce product ID or slug instead?
Yes. The extension supports the numeric WordPress / WooCommerce product ID and product slug as alternative match methods. Use one identifier method consistently within a batch.
How do I add several images to one WooCommerce product?
Use the same identifier with ordered suffixes, such as SKU123.0.jpg, SKU123.1.jpg, and SKU123.2.jpg. Leave Overwrite disabled for that multi-image run, review the gallery order, and decide featured image separately.
Can the uploader set a product’s featured image?
Yes. The Set as featured image option sets the uploaded file as the main product thumbnail for a simple or parent product. If it is enabled for several files that map to the same product, the last processed file becomes the final featured image.
Can I upload an image directly to a WooCommerce variation?
Yes. Match the file using that variation’s own SKU or variation ID. By default, the upload targets the variation’s individual image. Use Upload to parent product only when the image should be part of the shared parent gallery instead.
Can I replace an existing product gallery?
For the current extension, use Overwrite only for a controlled one-image replacement. Do not use it for a multi-image replacement batch because only the last processed image remains in the gallery. Back up first and verify a single test product.
What file types can I use?
The current uploader queue accepts JPG/JPEG, PNG, GIF, and WEBP files up to 10 MB. WordPress server configuration can still affect whether a particular file uploads successfully.
Does this change product titles, prices, or stock?
No. The verified implementation works with WordPress media attachments, product galleries, featured-image fields, and variation image fields. It does not alter product names, descriptions, prices, or inventory.
When BL Bulk Product Image Uploader fits
BL Bulk Product Image Uploader for WooCommerce fits catalogues where the image library already carries reliable SKUs, IDs, or slugs and the merchant needs a reviewable way to attach those files to existing products. It is not a replacement for clean catalogue data, product-image quality control, backup discipline, or a staging test where a store has custom product-gallery behavior.
Start with a small, representative batch. When the filenames, matches, gallery order, featured image, and variation behavior are correct, move to the remaining files. Review BL Bulk Product Image Uploader on the WooCommerce Marketplace or return to the cross-platform Bulk Product Image Uploader overview.