SHOPIFY IMAGE CSV GUIDE
Shopify CSV images not importing? Check these 8 things
A product can import while its images fail separately. The file might contain a local path, a protected sharing page, the wrong image column, a duplicate position, or a URL that returns something other than a usable image.
Check image fields privatelyQUICK ANSWER
Give Shopify a public image, the right product group, and an unambiguous position.
The URL must work outside your computer and without a login or private-network access.
Additional product image rows still need the exact handle of the product they belong to.
Confirm one small image group in Shopify before retrying the whole catalog.
IMAGE IMPORT CHECKS
What each failure usually means
Image could not be downloadedThe CSV points to your computer instead of the public web
A value such as C:\catalog\front.jpg, file:///Users/name/front.jpg, ./images/front.jpg, or a private network address only works in your own environment. Shopify’s importer cannot open a file from your computer or office network.
Upload the source image to a stable public host, then put its complete https:// URL in the CSV. Do not paste a local file path or a relative path from your website project.
An error occurred while trying to download the imageThe address requires a login, cookie, token, or temporary permission
A cloud-drive sharing page is not necessarily a direct image response. Signed URLs can also expire between file preparation and import. Hosts can block automated requests even when the image appears for you in an authenticated browser.
Open the exact URL in a private browser window. It should display the intended image without a login, consent step, or expiring permission. Prefer a stable HTTPS address that you control.
Invalid CSV headerThe URL is under the wrong image column or template version
Shopify’s current and classic product CSV formats use different header labels. Product images and variant image assignments are separate concepts. Renaming, translating, or mixing image columns can leave a valid URL unmapped.
Start from a current Shopify sample CSV or a fresh export from the target store. Keep its headers exact. Put the product image in the product image URL column and the variant-specific assignment in the variant image URL column used by that template.
Image position is invalid or duplicatedAdditional image rows do not clearly belong to one product
Multiple product images need to stay inside the same product group. A missing or changed handle can detach an image row. Repeating an image position makes the intended order ambiguous, while zero, negative, or decimal positions are not useful sequence values.
Repeat the exact product handle on each additional image row. When your template includes image position, use distinct positive whole numbers such as 1, 2, and 3 within that product.
Variant image was not assignedThe product image imported, but the variant row points somewhere else
A variant image belongs to a specific variant row. The row still needs the same handle and valid option combination as the rest of the product. A blank, malformed, or misplaced variant image field can leave the product gallery intact without assigning the image to the intended variant.
First repair the product’s handle and option grouping, then place the intended public URL in the variant image field on the correct variant row. Confirm the assignment in Shopify’s import preview and on the test product.
Unsupported or invalid imageThe URL returns a document, web page, SVG, archive, or misleading response
A URL can be syntactically valid while ending in .pdf, .html, .svg, or .zip. Some download endpoints also return an HTML error page with a successful-looking address. File requirements can change, so Shopify’s current product media documentation is the final authority.
Use a normal raster product image such as JPEG, PNG, WebP, or GIF when appropriate. Open the exact address and verify the response is the image itself, not a preview page or download error.
Product imported without all imagesThe file passed local checks, but Shopify could not complete the remote fetch
URL syntax is only the first gate. DNS, redirects, rate limits, host availability, response time, and the actual media payload are remote conditions. A privacy-first browser validator should not fetch every supplier or catalog URL on your behalf.
Test one product with one stable image first. Review Shopify’s result, retry only after fixing the host or URL, and avoid repeatedly submitting the same unchanged file.
Invalid header or illegal quotingThe image fields are correct, but the CSV row structure is broken
A comma inside a title, an unclosed quote, renamed header, or wrong delimiter can shift the image URL into another column. The spreadsheet may still look aligned even though the exported text is not.
Save as comma-separated UTF-8, preserve Shopify’s header row, and inspect quoted cells near the first failing image row. For broader price, inventory, category, and reference errors, use the complete Shopify CSV import error guide.
KNOW THE BOUNDARY
What can be checked before Shopify fetches an image?
Merch Preflight checks locally
- Malformed, relative, and local file paths
- Localhost and common private-network hosts
- Insecure HTTP image sources
- Obvious document and archive extensions
- Invalid or duplicate image positions
Shopify must check
- DNS, redirects, and host availability
- Whether access is blocked or rate-limited
- The response type, dimensions, and file size
- Store-specific product and variant matching
- The final image processing result
Your catalog and image URLs stay in this browser.
FIVE-MINUTE TEST
Before you retry the image import
- 1Filter to one product
Use one handle and a small set of images for the first test.
- 2Open every URL privately
Confirm that no login, cookie, or private network is required.
- 3Check columns and positions
Keep exact headers and use unique positive positions inside the product group.
- 4Validate the exported CSV
Catch shifted columns, malformed URLs, and obvious non-image downloads.
- 5Review Shopify’s result
Confirm the gallery order and variant assignments before a catalog-wide import.
FAQ
Shopify image CSV questions
Why are my Shopify CSV images not importing?
Start with the exact URL. It must be public, stable, and mapped to the correct image column. Then confirm the product handle, image position, variant row, and exported CSV structure.
Can a CSV upload images from my computer?
No. Local paths only exist on your computer. Host the image at a public HTTPS address before placing it in the product CSV.
How do I add multiple product images?
Keep the same handle on the image rows, add each public product image URL in the correct column, and use distinct positive positions when the template includes an image position field.
Does a clean validation report guarantee the image will import?
No. Local checks can find deterministic field problems without contacting the host. Shopify still decides whether its servers can download and process the remote file.
Official references
This guide follows Shopify’s current documentation on using product CSV files, common product CSV import problems, and product media requirements. Shopify can change its templates and processing rules; its current documentation and import result remain the final authority.