P
Portaim

Shopify Images via CSV: Multiple Images, Ordering, Variant Images, Alt Text

Shopify CSV Import Images Product Media

If you’re importing products into Shopify with a CSV file, image issues can happen—wrong URLs, unexpected ordering, duplication in some cases, or variant images not applying as you expected. This guide walks through Shopify’s CSV image columns, the “one row per image” rule, ordering with Image Position, variant image limits, alt text, and common import errors (with meanings taken from Shopify’s docs).

How Shopify CSV images work (core columns)

Shopify’s product CSV supports image-related columns that control where images come from, how they display, and how they’re described.

Product Image URL (Image Src): what it does (and what it doesn’t)

  • What it does: You enter a URL for a product image. Shopify downloads the image during import and re-uploads it into your store.
  • File naming note: Shopify recommends ensuring the image filename is final because you can’t edit it after upload, and avoiding _thumb, _small, _medium suffixes.
  • Not variant-specific: Shopify notes this column is not specific to variants. If you need variant-specific images, use the Variant image URL column.

Variant Image URL: when to use it (vs Product Image URL)

  • Use Variant image URL to add variant images.
  • Shopify’s docs emphasize: ensure added URLs are functioning image URLs.

Image Position: how ordering works (ascending from 1)

  • Image Position is a number that represents the order images display on the product page.
  • Images display in ascending order, starting from 1 (so 1 displays first).

Image Alt Text: limits and recommendations

  • Alt text describes the image and product.
  • If an image can’t load, alt text can display instead.
  • Shopify notes alt text supports accessibility (screen readers) and can boost SEO.
  • Maximum length is 512 characters; optimal is 125 characters or fewer.
  • Shopify confirms you can upload alt text in a CSV file.

Step-by-step instructions: add multiple images, order them, set alt text, and (optionally) add variant images

Step 0 — Safety prep (do this first)

  1. Back up your product data before importing. Shopify explicitly recommends this.
  2. Consider running a small test import (for example, a few products) to confirm image URLs, ordering, and variant image assignment before importing a full catalog.
  3. Product imports started with a CSV file can’t be cancelled once they begin.
  4. Be careful with spreadsheet sorting (see “Common pitfalls”)—Shopify warns it can break image links and cause images to be lost.

Step 1 — Prepare image URLs (public and direct)

  1. Ensure images are hosted on an existing website (a CSV file can only contain text).
  2. Use only image URLs in the CSV. Shopify says 3D models and videos aren’t supported for the CSV, but you can upload them to Content > Files.
  3. Make sure external URLs are publicly accessible.
  4. For multiple images, Shopify notes they should be behind an https:// protocol with no password protection.

If your files are only on your computer, Shopify suggests uploading them to:

  • Shopify Admin > Content > Files, or
  • another image hosting service (examples Shopify mentions: GoDaddy, OneDrive, Dropbox, BucketLynx), then obtaining the URL.

Step 2 — Decide where each image should go (product vs variant)

  • Product images: use Image Src (Product image URL / Image Src).
  • Variant images: use the Variant image URL column (not Image Src).

Step 3 — Add multiple images (Shopify’s “one row per image” rule)

Shopify’s documented rules for multiple images are specific:

  • You can add up to 250 images to a product.
  • You must use only one row per image.

Workflow (Shopify’s steps):

  1. Insert new rows — one new row for each additional image.
  2. Copy and paste the Handle value into column A for each of those new rows.
  3. In the Image Src (Product image URL) column, paste one image URL into each line.
  4. (Optional) Add Image Alt Text on each image row.

Short example CSV snippet:

Handle,Title,Image Src,Image Position,Image Alt Text
my-product,My Product,https://example.com/img1.jpg,1,Front view of My Product
my-product,,https://example.com/img2.jpg,2,Side view of My Product
my-product,,https://example.com/img3.jpg,3,Back view of My Product

Shopify’s docs emphasize repeating the same Handle value on the additional image rows. For how to fill other fields on those rows, verify your CSV template in Shopify Admin / Help Center.

Step 4 — Control ordering with Image Position

To order images:

  1. Add an Image Position value per image row.
  2. Use 1 for the first image, 2 for the second, and so on.

Shopify states images display in ascending order, starting at 1.

Example ordering:

Handle,Image Src,Image Position
my-product,https://example.com/hero.jpg,1
my-product,https://example.com/detail.jpg,2
my-product,https://example.com/lifestyle.jpg,3

Step 5 — Add alt text (accessibility + SEO)

  1. Fill Image Alt Text for each image row.
  2. Keep it brief and descriptive.
  3. Stay within Shopify’s guidance: max 512 characters, recommended 125 or fewer.

Examples (brief + descriptive):

  • Black leather wallet, front view
  • Blue ceramic mug on a wooden table

Step 6 — Add variant images (and respect the limits)

Shopify’s variant image rules include:

  • You can add only one image to each product variant.
  • Product variants don’t support 3D models or videos.

To add a variant image:

  1. Use the Variant image URL column.
  2. Ensure the URL is a functioning image URL (Shopify’s wording).

Shopify also mentions that merchants on Plus and enterprise commerce plans can use the Shopify Combined Listings app to combine individual products into a single listing, allowing additional images for product options.

Step 7 — Import (and watch for Shopify’s confirmation email)

  1. Upload your CSV in Shopify Admin (verify the exact navigation in Shopify Help Center if you don’t see the import option).

  2. Shopify notes:

    • Imports can’t be cancelled once they begin, and
    • after your CSV file is uploaded, Shopify sends a confirmation email to the email account used to set up your Shopify store.

Common pitfalls (and how to avoid them)

Pitfall 1: Sorting the CSV in Excel/Numbers (images can be lost)

Shopify warns that importing a CSV 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.

What to do:

  • If you must reorganize rows, be extremely careful to keep each image row tied to the correct Handle.
  • Consider validating the outcome with a small test import before importing your full file.

Pitfall 2: Using the wrong column for variant images

Shopify explicitly says the Product image URL column is not specific to variants. If variant images aren’t applying, verify you’re using Variant image URL.

Pitfall 3: Non-public or broken image URLs

Shopify requires image URLs (especially external ones) to be publicly accessible. If you’re seeing import errors, use the error messages section below to match the exact wording Shopify provides.

Pitfall 4: CSV file too large

Shopify states your product CSV can’t exceed 15 MB. If you get an error or upload times out, Shopify recommends splitting into smaller files and uploading each file.

Pitfall 5: Image file name restrictions (especially in Files uploads)

Shopify’s Files requirements include filename rules. For images uploaded to Content > Files, filenames:

  • must not begin with a period .
  • can’t end with: pico, icon, thumb, testing, small, compact, medium, large, grande

Shopify notes these endings can be misinterpreted as image transformation requests by Shopify’s CDN.

Pitfall 6: Duplicate images when using Files URLs in your CSV (expected behavior)

If you link to an image hosted in Shopify Content > Files from your CSV, Shopify documents an “expected behavior” where the image is redownloaded and duplicated (details below).

”Files” URL duplication behavior (expected)

Shopify states:

  • When uploading a product with a CSV file that includes a link to an image in the Files area, the image is redownloaded and duplicated.
  • The duplicated image exists in the /products/ folder, and the original remains in the /files/ folder.
  • Shopify calls this expected behavior.

Shopify also notes how to avoid duplication:

  • Host images elsewhere, or
  • Upload images directly to products after importing the CSV.

Shopify Community threads also describe merchants seeing a “copy” with a long number string appended to filenames after importing from Files URLs, consistent with the official explanation.

Shopify’s Files documentation lists image requirements:

  • Max file size: 20 MB
  • Max resolution: 20 MP (megapixels)
  • Aspect ratio: between 100:1 and 1:100
  • Formats: JPEG, PNG, WEBP, HEIC, GIF

Filename restrictions (for Files uploads):

  • File names must not begin with a period .
  • Image file names can’t end with: pico, icon, thumb, testing, small, compact, medium, large, grande

Common Shopify CSV image errors (meaning + fix direction)

The meanings below are taken from Shopify’s “common import issues” guidance.

1) “Validation failed: getaddrinfo: nodename nor servname provided, or not known”

Shopify says this error is caused by a mistake in the image URL:

  • The image URL needs to have http:// in front of it.
  • It also needs to be a publicly accessible direct link to the image.

2) “Validation failed: An error occurred while trying to download the image”

Shopify says: an image file is missing.

3) “Validation failed: The uploaded image exceeds the 20 megapixel limit”

Shopify’s guidance says:

  • Product images can be any size up to 5000 × 5000 px, or 25 megapixels.
  • Reduce the size of the image or use a different image.

Note: Shopify’s Files page also lists a 20 MP maximum for uploaded files in the Files section. If you’re seeing different limits in different contexts, follow the exact error message you’re receiving and verify in Shopify Admin / Help Center.

4) “Incorrect header check”

Shopify’s guidance suggests:

  • Remove the image from that line and try again.
  • If that resolves the issue, try hosting the image somewhere else.

Safety notes before you import (backup, small test batch, overwrite risk)

  1. Back up your product data first. Shopify explicitly recommends this before importing.
  2. Consider a small test import (a few products and images) before importing a full catalog.
  3. You can’t cancel a CSV import once it begins.
  4. Be careful with spreadsheet sorting. Shopify warns sorting in Excel/Numbers can break image links and cause images to be lost.
  5. Understand “missing column” behavior. Shopify notes that if a non-required column isn’t included in the import CSV but exists on the product already, then the existing value remains the same (example they give: Variant image URL).
  6. If you’re unsure how your CSV will affect your specific products, verify in Shopify Admin / Help Center before importing.

FAQ

1) How many images can I add to one Shopify product via CSV?

Shopify’s documentation says you can add up to 250 images to a product.

2) Do I need one CSV row per image, or can I put multiple image URLs in one row?

Shopify says: “You must use only one row per image.” For multiple images, insert new rows and repeat the product Handle.

3) How does Shopify decide the order images display (Image Position)?

Shopify says images display in ascending order by Image Position, starting at 1.

4) What’s the difference between Product Image URL (Image Src) and Variant image URL?

Shopify says the Product image URL column is not specific to variants. Use the Variant image URL column to add variant images.

5) Can a single variant have multiple images?

Shopify says you can add only one image to each product variant.

6) What is the maximum length for image alt text in Shopify CSV, and what length is recommended?

Shopify says the maximum alt text length is 512 characters, and 125 characters or fewer is recommended.

7) Why did my image get duplicated from the Files area into the /products folder after CSV import?

Shopify documents that when your CSV links to an image in the Files area, Shopify redownloads and duplicates it. The duplicate exists in /products/, and the original remains in /files/. Shopify calls this expected behavior.

8) What does “getaddrinfo: nodename nor servname provided” mean during image import?

Shopify says it’s caused by a mistake in the image URL: the URL needs http:// and must be a publicly accessible direct link to the image.

9) What does “An error occurred while trying to download the image” mean?

Shopify says it means an image file is missing.

10) What does “The uploaded image exceeds the 20 megapixel limit” mean?

Shopify’s guidance says reduce the image size or use a different image, and notes product images can be up to 5000 × 5000 px or 25 megapixels (per the common import issues page). If you’re seeing a different limit in your context, verify in Shopify Admin / Help Center.