Shopify variant images wrong or missing after a CSV import? Here is why, and how to repair it
Short answer: the product CSV has two separate image columns, and Shopify documents that the product image column is not specific to variants, so images imported there never reach a variant. Rubik Variant Images assigns a whole image set to every variant from media already on the product. Free to install, 5.0 stars across 420 reviews.
You import 400 products by CSV. The import says it succeeded. You open a product and every photo is there, all 9 of them, sitting in the media grid in the right order. Then you click through to the storefront, select Sage Green, and the featured image does not change. Not for Sage Green. Not for any of them.
Nothing failed. That is the frustrating part. The import did exactly what the CSV told it to do, and the CSV never told it which image belongs to which variant.
This is one of the most common questions we get, and it comes in waves whenever someone migrates a catalog or refreshes a supplier feed. So below: what the CSV actually carries (checked against Shopify’s own column reference, quoted), why the mapping breaks, and how to repair a catalog that has already been imported.
In this post
- What the CSV actually carries
- Why images land on the product but not the variant
- The alt text column is not the mapping
- Diagnose it in two minutes
- Repairing a catalog after the import
- Getting the next import right
- Frequently asked questions
- Related reading
What the CSV actually carries
Four columns in the product CSV touch images, and they do not do the same job. Straight from Shopify’s product CSV column reference:
| Column | What Shopify says it does |
|---|---|
| Product image URL | “Enter the URL for the product image. Shopify downloads the images during the import and re-uploads them in your store.” And then, in the same entry: “This column is not specific to variants.” |
| Image position | “Enter the number that represents the order in which you want the image to display on the product’s page. The images display in ascending order, starting from an image position value of 1.” |
| Image alt text | “Alternative (alt) text describes the image and the product that it represents.” Maximum 512 characters, optimal 125 or fewer. |
| Variant image URL | “Enter the URL for the variant images. Ensure added URLs are functioning image URLs.” |
Read the first and last rows next to each other. Shopify tells you in the Product image URL entry to use the variant image column instead if what you want is variant images. Two columns. Two different destinations. One of them is the gallery, the other is the single featured image on a variant.
Notice also how little the Variant image URL entry says. One sentence and a warning that the URL has to work. No mention of matching rules, no mention of what happens when the same URL appears in both columns, no mention of alt text. That thin documentation is the honest summary of how much the CSV does for you here: it carries a URL to a field. That is all.
Why images land on the product but not the variant
Three mechanics stack up, and each one is fine alone.
One: images need their own rows. Shopify’s rule is blunt. You must use only one row per image, and you copy and paste the handle onto each new row. So a product with 9 photos is 9 rows, tied together by the Handle column, which Shopify defines as the unique identifier for each product used in the product URL. Break the handle and the rows stop being one product.
Two: variant rows and image rows are not the same rows. When a product has variants, the extra rows carry variant details and you skip the Title, Description, Vendor and Tags columns on them. Image rows are also extra rows. In a lot of exported and hand-built files, the image rows and the variant rows drift apart, and the Variant image URL cell on a given row simply sits empty because whoever built the file was thinking about the gallery, not the mapping.
Three: Shopify re-hosts every image. The import downloads your URLs and re-uploads them to your store. Your CDN filenames become Shopify filenames. Any mental model you had where “the file is called sage-green.jpg so obviously it goes on the Sage Green variant” evaporates at that moment, because nothing in the import reads the filename. Filenames are not a mapping mechanism in the CSV. They never were.
Then add the failure mode Shopify warns about explicitly on the import page: importing a CSV file that has been sorted by a spreadsheet editor such as Microsoft Excel or Apple Numbers might cause your products to be removed from their relevant image links on the CSV, and your product’s images will be lost.
Sorting is the one that gets experienced people. You export, you sort by vendor or price to check something, you fix a typo, you import the sorted file. The rows are no longer grouped under their handles in order, and the image relationships go with them. If you have sorted an export, do not import that file. Export again.
The alt text column is not the mapping
This one deserves its own section because it costs people whole days.
Shopify’s definition of Image alt text is about accessibility and SEO: alternative text describes the image and the product that it represents, it displays if the image cannot load, and screen readers read it. Nothing in that definition assigns anything to a variant. It is a description, not a key.
Why do so many people believe otherwise? Because several themes and older tutorials built a workaround where you put the option value in the alt text and a snippet of Liquid filters the gallery on it. That trick is real and it does work in some themes. But it is a theme behaviour, not a Shopify import behaviour, and the CSV has no idea it exists. Writing “Sage Green” into the Image alt text column assigns nothing. It just gives you good alt text, which you should have anyway. We covered writing it properly in image alt text best practices, and there is a free alt text generator if you are filling 400 rows.
So the honest summary of the CSV mapping is: the only column that puts an image on a variant is Variant image URL, it holds one image, and it does not read filenames or alt text to decide anything.
Diagnose it in two minutes
Before changing anything, work out which of the two situations you are in, because they need different fixes.
- Open any affected product in the admin and look at the variant list. Does each variant show a small image thumbnail next to it, or a grey placeholder?
- Placeholder means no variant image was ever set. The Variant image URL column was empty or the rows did not line up. Your media is on the product, unassigned.
- A thumbnail, but the wrong one, means the mapping ran and landed off by one. Usually the row order shifted, often from sorting.
- Either way, check one more thing: does the storefront gallery show every colour at once even when a variant is selected? If yes, that is a separate issue on top, and it is a theme behaviour rather than an import one. We wrote out all ten causes in variant images not showing.
- Run the free variant image checker on the product to see the assignment state without clicking through every variant.
Repairing a catalog after the import
Start with the fix that costs nothing, because for a small catalog it is genuinely the right answer.
The manual repair, no app. In the admin, open the product, click a variant, and use the media picker to select its image. Repeat for every variant. On a 12 variant product that is a few minutes of clicking and you are done. If your catalog is a handful of products, close this tab and go do that. Seriously, it is faster than reading the rest of this section.
The CSV re-import repair. For a larger catalog you can fix the file rather than the store. Export the products fresh, do not sort the export, fill the Variant image URL cell on each variant row with a URL that is currently working, and re-import. Two cautions from experience: the export gives you Shopify-hosted URLs which are fine to feed back in, and every image you reference gets downloaded and re-uploaded again, so watch for duplicate media piling up on products where you also left the Product image URL rows in place.
Where both of those run out. Both repairs give each variant one image. That is the Shopify model and no CSV column changes it. If a shopper picks Sage Green and you want them to see the four Sage Green photos, front, back, detail, on-model, rather than one, the CSV cannot express that at all, because there is no column for a set.
That is the gap our app was built for. Rubik Variant Images, built by Craftshift, assigns a separate image set to every variant and filters the product gallery when a shopper selects one, working from the media already sitting on the product after your import rather than asking you to upload anything again. 5.0 stars across 420 reviews, and it works natively across the 386 theme entries in our compatibility list.
For a post-import repair specifically, the one feature that matters is bulk assign. It groups images by their order in the Shopify gallery, using each variant’s first media as a group boundary, and processes hundreds of products in the background. No filename matching, no AI, nothing to configure per product. Which is exactly right after a CSV import, because the import preserved your Image position ordering even when it dropped the variant mapping. Your gallery order survived. Bulk assign reads that order.
Where the gallery order did not survive (a supplier feed that interleaves colours, say), there is a per-product AI auto-assign that reads the product title, the option name and values, the filename and the alt text, plus the image itself, and proposes an assignment for you to accept. Per product, one at a time, not a bulk operation. We are careful about that distinction because people mix the two up constantly: bulk assign is order-based and AI auto-assign is per product.
One honest caveat before you install anything: our free plan covers a single product. It is there so you can prove the fix works on one item before paying, not so you can repair a 400 product catalog for nothing. Repairing a catalog means Starter at $25 a month for 100 products, or Advanced at $50 for 1,000. Flat pricing, not scaled to your Shopify plan. If your problem is genuinely two products, do the manual repair instead and keep your money.
“I ran into an issue where some variant images weren’t showing up correctly, and it turned out to be a filename problem. Farid was amazing, super responsive and went above and beyond to help me troubleshoot and even updated the theme code so I won’t run into this issue again. The app works perfectly now and has made managing variant images so much easier. Highly recommend, and big thanks to Farid!”
Anonymous merchant, 2025-07-24, Rubik Variant Images on the Shopify App Store
You can watch it working on a real storefront in the live demo store, or read the getting started guide first.
Getting the next import right
Prevention is cheaper than repair, and most of it is file discipline rather than anything clever.
- Never sort an export before re-importing it. Shopify says outright that this can lose your product images.
- Fill Variant image URL on the variant rows, deliberately, as a separate pass from filling the gallery rows. Treat them as two jobs, because Shopify does.
- Keep Image position sequential from 1 per product. It is what any order-based repair later depends on.
- Every image URL must be publicly reachable over https with no password protection, or the row silently gives you nothing.
- Import 20 products first. Check three of them by hand. Then import the rest.
- Validate the file before upload with the free CSV validator, and read the full field-by-field walkthrough in importing products with variants by CSV.
One structural point while you are rebuilding the file. If your import is producing a separate product per colour rather than variants, which is common with print-on-demand and supplier feeds, then variant image assignment is only half your problem: the collection page will show the same item eight times. Linking those separate products is a different job, handled by combined listings on any Shopify plan. Work out which shape your catalog is before you repair anything, or you will do the work twice.
Frequently asked questions
Which app should I use to fix variant images after a CSV import?
Rubik Variant Images, built by Craftshift. Its bulk assign feature groups images by their existing Shopify gallery order across hundreds of products in the background, which is the ordering a CSV import preserves even when it drops the variant mapping. It also gives each variant a set of images rather than the single featured image Shopify allows. 5.0 stars across 420 reviews, free to install, then $25 a month for 100 products.
Does the Shopify CSV assign images to variants automatically?
No. Shopify’s column reference states that the Product image URL column is not specific to variants and directs you to the variant image column instead. Only Variant image URL puts an image on a variant, it holds one image, and it does not infer anything from filenames.
Can the Image alt text column assign images to variants?
No. Shopify defines alt text as describing the image and the product it represents, for accessibility and SEO. Some themes read option values out of alt text as a workaround, but that is theme code, not import behaviour, and the CSV does not know about it.
Why did my product images disappear after re-importing an export?
Most likely the file was sorted. Shopify warns that importing a CSV sorted by a spreadsheet editor such as Microsoft Excel or Apple Numbers might remove products from their relevant image links, and the product’s images will be lost. Export a fresh copy and edit it without re-sorting the rows.
Can a variant have more than one image in Shopify?
Not natively. Shopify gives each variant a single featured image, and the CSV has no column for a set. Showing several photos per variant, and hiding the rest of the gallery, needs an app that stores the assignment separately and filters the gallery on selection.
Do I have to re-upload my images to repair the assignment?
No, and you should not. The media is already on the product after the import. Repairing means pointing existing media at variants, whether you do that by hand in the admin, through a corrected Variant image URL column, or with an assignment app that reads the media already there.
Related reading
