Shopify CSV images · verified 2 August 2026
How do product images work in a Shopify CSV?
Use a publicly reachable image URL, attach it to the correct product handle, and keep product images distinct from variant images. A product with several images can use additional rows that repeat the product's URL handle while leaving unrelated product fields blank. Shopify fetches the remote files during import, so a structurally valid CSV cannot prove that an image will remain reachable.
What kind of image URL can Shopify import?
Shopify's product CSV guidance requires image URLs to be publicly accessible. A URL that works only after signing in, points to a private drive, expires after a short time, blocks automated requests, or depends on a local computer cannot be reliably fetched by Shopify. Use HTTPS and test the URL in a private browser window before import.
Do not use the address of a web page that happens to display an image. The CSV field should point to the image file itself. Redirects, rate limits, hotlink protection, content-type errors, or an unavailable origin can still make the import fail even when the string looks like a valid URL.
How are several product images represented?
The first image can appear on a product or variant row. Additional product images use additional rows with the same URL handle so Shopify associates them with the same product. The image URL belongs in the product image column; image position can control ordering when supplied. Shopify currently documents a maximum of 250 images per product.
| Row purpose | URL handle | Product image URL | Other product fields |
|---|---|---|---|
| Primary product/variant row | Repeat the product handle | May contain the first image | Contains the fields needed for that product or variant |
| Additional product image | Repeat the same handle | Use the next public image URL | Leave unrelated fields blank |
A blank handle on an image-only row can orphan the image. A different handle can attach it to the wrong product. Sorting only the image column or only the handle column can silently destroy these relationships, so always sort complete rows together.
What is the difference between a product image and a variant image?
A product image belongs to the product gallery. A variant image links a particular variant to an image. The variant relationship depends on the row's complete option structure. If a row has a variant image but incomplete Option1 data, the file has both an image-mapping risk and a variant-identity risk.
Use the documented current headers or the matching legacy names from the export you are working with. CatalogVigil recognises legacy names such as Image Src and Variant Image and can preview a rename to their current equivalents without changing the original file.
Why can an image import fail after the CSV passes preflight?
- The server returns an error, login page, HTML page, or unsupported response instead of an image.
- The URL expires or is rate-limited before Shopify fetches it.
- Robots, hotlink, firewall, or geographic rules block Shopify's request.
- The image is too large, damaged, or in an unsuitable format.
- The handle or variant option data associates the row with the wrong product.
- A redirect changes or stops working between preparation and import.
A browser-local validator should not contact every image host: doing so would disclose the URLs, create extra network traffic, encounter cross-origin restrictions, and still fail to reproduce Shopify's own fetch environment. CatalogVigil therefore validates URL shape and row relationships, then leaves availability to Shopify's import process.
How should image alt text be written?
Where the CSV includes image alt text, describe the useful visual information briefly and in the language of the storefront. Avoid stuffing keywords or repeating surrounding product copy. Decorative details do not need a long description, while meaningful differences such as colour, angle, or packaging may help a customer understand the image.
A safer image-import sequence
- Keep an untouched product export and a list of the current image order.
- Verify every new URL in a signed-out/private browser window.
- Group all rows for one product together and repeat its handle on image-only rows.
- Keep product-image and variant-image columns semantically separate.
- Run a local preflight for missing handles, malformed URLs, row-width problems, and incomplete variants.
- Import a small sample and wait for Shopify's image processing to complete.
- Inspect gallery order, variant selection, alt text, crops, and storefront output before scaling up.
Primary source: Shopify Help Center: Using CSV files to import and export products. Availability and platform limits can change; verify the current Shopify documentation before a large import.