Shopify Bulk Alt Text CSV: Template and Column Guide

Sample file

Three sample rows, generated by the same code that powers the Shopify export.

Handle,Image Src,Image Position,Image Alt Text
blue-ceramic-mug,REPLACE_WITH_IMAGE_URL/blue-ceramic-mug.jpg,1,Blue ceramic coffee mug with a wide handle on a wooden table
linen-tote-bag,REPLACE_WITH_IMAGE_URL/linen-tote-bag.jpg,1,Natural linen tote bag with leather straps hanging on a hook
brass-desk-lamp,REPLACE_WITH_IMAGE_URL/brass-desk-lamp.jpg,1,"Brass desk lamp with an adjustable arm, switched on"

Steps

1. Generate alt text for your product photos with the alt text generator and read every line.
2. Choose the Shopify CSV export and open the file in a spreadsheet.
3. Replace each Handle with the real handle of the product the image belongs to. The handle is the last part of the product's web address.
4. Replace each REPLACE_WITH_IMAGE_URL placeholder with the full web address of the image that is already on that product.
5. Back up your products with a Shopify export, then import a few rows first and check the result in the admin.

Start with the Alt text generator, then check the text with the alt text checker.

What each column does

Handle identifies the product. Shopify uses it to decide which product a row belongs to, so it has to match an existing product exactly. Neartool cannot know your handles, so the sample fills it from the file name. That is only a starting point and it will not match your store until you replace it.

Image Src is the web address of the image. Shopify downloads the image from this address during import. Neartool never sees where your photos are hosted, so it writes a placeholder instead of a guess. Image Position is the order of the image on the product, where 1 is the main image. Image Alt Text is the description Neartool wrote for that photo.

Why a wrong handle causes trouble

If a handle does not match an existing product, Shopify treats the row as a new product or rejects it, depending on your import settings. Shopify's help pages describe overwriting products that have matching handles, but they do not say exactly what happens to an image that is already on the product when the same image address appears again. Do not assume it will simply update the old image.

Because of that gap, test with two or three products before a large import. Look at each product afterwards and check that the image count did not double and that the alt text changed on the image you meant.

When the CSV is not the right tool

For a handful of products, typing alt text into the media editor in the Shopify admin is faster and safer than preparing a file. The CSV route pays off when you have dozens of products and the same person is already editing a spreadsheet of titles and descriptions.

You can also use the exported file as a reference sheet. Read the alt text for each image, then paste it into the admin by hand. Nothing is lost by treating the file as a worksheet, and you avoid any risk to your catalogue.

Keep the text useful

Describe what the shopper can see: the product, its colour and one detail that tells it apart from similar items. Skip phrases such as image of, avoid repeating the product name on every photo in the gallery, and never fill the field with search keywords. Neartool's drafts come from a small model that sees only the photo, so check colours and details before you import.

Limits and facts

Frequently asked questions