Shift my head back into gear though, because Shopify bulk variant images csv is one of those topics that looks easy in the docs and turns into a Friday-night nightmare in practice. The product CSV has an Image Src column that you’d assume means you can load up all the bulk variant images in one csv file but nope. Then you have to fill out a separate Variant Image column per row that absolutely overrides that value in the Image Src column and then Shopify gives you one nice friendly error message explaining why the image fails to upload due to its size but then gives you a completely unhelpful URL in the error message that’s from your *own* Shopify CDN and one silly space in the wrong place in their required format means you get a 500 Internal Server Error.
A concrete workflow including information about the necessary structure of the CSV, the own rules which we decided for the hosting of the images, our experience about gotchas and where we found out it is better to actually start designing an application and stop building such a workflow.
Table of contents
- How Shopify CSV handles images
- Image hosting requirements
- The “multiple per variant” gap
- A working workflow
- Common errors and fixes
- FAQ
How Shopify CSV handles images
The Shopify product import csv file has two columns referring to images: Image Src and Variant Image. They are used differently and I couldn’t find decent information on the Shopify.com tech docs for how to use them.
Image Src is the product gallery. Each row of the gallery represents an image, and to add 5 images to a product you would add 5 rows to the product description. The first row would have the product handle, title, and all of the regular product fields filled out, and the next 4 rows would only have the handle and a new Image Src URL. The gallery is then generated by Shopify and uploaded to the product page.
Variant Image is a featured image for individual variants. You add Variant Image on the variant rows and it gives you a separate URL for each variant. That URL has to exist in the product gallery (the Image Src list above the product gallery) otherwise Shopify will simply ignore it and you will be none the wiser. This is a trap that catches many people out as they want to add more images to their product so they copy in a fresh URL hoping that the image will be uploaded as a variant image, when in fact it wont.
Result: native CSV requires one image per variant. Same featured image limitation as #5 above but in spreadsheet form.
Image hosting requirements
Three rules for the URLs you put in Image Src.
- HTTPS only. HTTP URLs fail silently in 90% of cases.
- Direct file URLs only. Dropbox shared links, Google Drive viewer links, and OneDrive previews all fail because they return HTML, not an image.
- Public access. The Shopify importer fetches the URL once and stores the file. If the URL requires auth, it fails.
Where to host? Three good options. Shopify Files (Settings, then Files) is the easiest option for image management on Shopify store. It stores image locally on your Shopify store and provides CDN-hosted URLs for easy access and public sharing. In fact, free CDN-hosted image URLs are already included with every Shopify store! For small stores under 5000 products, it is still the easiest option. For larger stores with 5000 products and more, cloudinary and AWS S3 with public bucket access are good options as well. They both provide free option for image storage (free tier for Cloudinary stores 25GB of image storage) for store owner to test and use as image management solution.
Quick note on Google Drive. Short answer: sometimes, in tiny bits, if you use a special URL format (uc?export=download&id=). Sometimes it fails silently, and you get a white screen of “checking”. It is extremely brittle, and Google rate limits heavily. Do not base any workflow on Drive working.
The “multiple per variant” gap
Native Shopify can only ever assign one image to a variant, no matter what (including a perfect CSV file).
You need an app to handle this. Here is how it typically works: you import the images via CSV as normal (all images import into product gallery and 1 image per variant is set as variant image). Then you have a product variant images app that looks at the gallery and then assigns images to variant based on file name, alt text, or order of image in gallery. So the CSV imports gallery, and app imports variant images from that gallery.
Two app methods work for this in practice:
- Image-order bulk assign. You upload images in color groups (5 blue images, then 5 red, then 5 green) and the app uses the gallery boundaries to create groups automatically. No matching needed. This is what Rubik Variant Images does, using the featured image as the group marker.
- AI auto-assign per product. The app reads the product name, variant name, image filename, and image alt text, and uses Claude AI to figure out which image belongs to which variant. Per-product, not bulk, but useful for cleaning up the long tail after a CSV import.
Both techniques can be done without creating a separate variant images CSV – the app uses the already imported gallery. There is set up instructions on rubikvariantimages.com.
A working workflow
| Step | Tool | Why |
|---|---|---|
| Sort images by color into local folders | File manager | Sets up image-order grouping |
| Compress to web sizes | Image compression tool | Faster upload, smaller CDN bill |
| Bulk upload to Shopify Files | Smart Bulk Image Upload | Get hosted URLs without paid CDN |
| Build the product CSV | Spreadsheet | Image Src column with Files URLs |
| Import the CSV | Shopify admin | Creates products and gallery |
| Run bulk variant assign | Variant images app | Adds the per-variant relationships |
| Spot check on a real product | Storefront preview | Catches the inevitable misfires |
My 500 page catalog takes about 90 minutes (with all the wait time included) to process. Product variants are assigned in a snap – the actual bottleneck is product upload and the import of the catalog CSV. Two tools have saved me hours of time on this project: Image Optim for image compression (it can compress hundreds of images in seconds), and the Shopify CSV Validator, which can check a 200-line CSV for malformed rows in seconds, catching problems that would take an hour to debug by hand.
Note: if your catalog has separate products for color (one product called “Shirt Blue” and another called “Shirt Red”), then you don’t need a variant images app anymore. You would just go with combined listings where each of the products “Shirt Blue” and “Shirt Red” get their own galleries but then are combined and listed in a single collection with collection swatches on the collection pages. Our Rubik Combined Listings app also supports bulk grouping of products in a CSV.
Common errors and fixes
“Image could not be downloaded”. Almost always an HTTPS or auth issue. Open the URL in an incognito window. If you do not see the image directly, Shopify cannot either. Please try to host in Shopify Files.
“Variant image not assigned”. The Variant Image URL must already exist in the Image Src list for that product. Double check the list of product rows above it to make sure the variant row’s image URL appears verbatim in the list.
“Duplicate handle” rejection. Shopify uses the Handle column as a primary key. Make sure the handles you enter are unique and only contain lowercase letters, numbers, and hyphens. No underscores or spaces are allowed in the handle.
“CSV upload timed out”. Files larger than 15MB or with more than 50,000 rows fail. Upload in chunks of 5,000 rows. It’s annoying, but it’s been that way since 2018.
“Images uploaded but in wrong order”. Shopify imports Image Src rows in the order that they appear in the list in the CSV. If you sorted your spreadsheet by alphabet then the gallery will upload in alphabetical order. You should sort your spreadsheet by the order that you want the images to appear BEFORE you save the file.
Two more resources to bookmark before you embark on your next batch of product imports: the 2048 variants image management guide for handling very large product catalogs and the app stack audit to make sure your imports don’t slow down your store as well.
FAQ
Can I bulk upload multiple variant images natively in Shopify?
You can upload multiple images for your products in your product CSV, but then Shopify only allows 1 image to be set per variant. There are variant images apps available that can read in the gallery and then assign the images to the correct variant for the cart etc.
What URL formats does the Shopify CSV importer accept?
HTTPS only, direct file URLs only, public access required. Shopify Files, Cloudinary, AWS S3 public buckets all work. Dropbox sharing links and Google Drive viewer links do not.
Why is my Variant Image column being ignored?
URL doesn’t exist in product Image Src list for that product. Shopify only allows variants in the application scope if they exist in the product gallery images list.
How big can my CSV be?
15MB and 50,000 rows is the practical ceiling for a single import. Larger files should be split into chunks of 5,000 rows or so before uploading.
Can I use Google Drive as image host for CSV import?
It sometimes works with special URL formatting but rate limits aggressively and is fragile. Use Shopify Files instead.
What if I want a different image set per color?
Upload all images as a big list separated by color groups (first all the blue ones and then all the red ones) and then do a bulk change to variants where you program the script to build per-variant relationships based on the order of the images in the list.
Does CSV import work for combined listings?
The standard product CSV is not going to have combined listings. There is an app for combined listings that allows you to do bulk grouping of the combined listings CSV.
Related reading
- Multiple images per variant
- 2048 variants image management
- Variant images complete guide
- Rubik Variant Images setup
- Bulk grouping combined listings
Done with wrestling your products through Shopify’s CSV import process? Check out Rubik Variant Images from the Shopify App Store. Assign bulk variant images.
