How to Bulk Add Alt Text to Shopify Product Images with a CSV
A step-by-step guide to filling in missing alt text across your whole Shopify catalog using the product CSV export and import. It includes a writing formula, worked examples and a pre-import safety checklist.
If your store has dozens or hundreds of product photos with empty alt text, adding it one image at a time in the Shopify admin is slow. The faster route is Shopify's own product CSV: export your products, fill in one column and import the file back.
This page walks through the whole process. It also covers how to write alt text that actually helps shoppers who use screen readers, and the mistakes that can damage your product data.
First, check how big the gap is
Before you start, find out how many images need work.
- In the admin: open a product, click an image and look at the alt text field. This is fine for a quick spot check.
- In a CSV export: export all products (steps below), open the file and filter the Image Alt Text column for blanks. Every blank row that has an Image Src value is a product image with no alt text.
Counting the blanks tells you whether this is an afternoon job or a weekend job.
Step 1: Export a backup (do not skip this)
- In Shopify admin, go to Products.
- Click Export.
- Choose All products and CSV for Excel, Numbers, or other spreadsheet programs.
- Save this file somewhere safe and name it something like backup-before-alt-text.csv.
Never edit this backup. If anything goes wrong during the import, it is your way back.
Then export a second copy. That second copy is the one you will edit.
Step 2: Understand the columns that matter
Shopify's product CSV has many columns. For alt text, only four matter:
- Handle: the product's unique ID in the CSV, such as speckled-stoneware-mug.
- Image Src: the URL of the image.
- Image Position: the image's order on the product (1, 2, 3...).
- Image Alt Text: the description you are adding.
A product with several images takes up several rows. The first row holds the product details. The extra rows often contain only the Handle and the image columns. That layout is normal, so don't "fix" it.
Step 3: Write the alt text
Fill in the Image Alt Text cell on every row that has an Image Src. Leave every other column exactly as exported.
A simple formula
[What it is] + [key visible details: color, material, shape] + [what this particular photo shows]
The last part is what keeps several photos of the same product from all getting identical alt text. Image 1 might show the front, image 2 the back and image 3 the item being worn or used. The alt text should reflect that.
Writing guidelines
- Describe what is in the photo, not what you wish it said for search engines.
- Keep it concise. A common guideline is roughly 125 characters or fewer, so the description is quick to listen to.
- Don't start with "image of" or "picture of." Screen readers already announce that it is an image.
- Use the product's real attributes, such as the color name, material and finish, especially when variants differ.
- No keyword stuffing. "Handmade mug ceramic mug pottery mug gift mug" helps nobody and reads badly aloud.
- Skip prices, discounts and calls to action. "Buy now, 20% off" is not a description of a photo.
Worked examples
Here is the same product described poorly and then well.
Product: Speckled Stoneware Mug, Oatmeal glaze, 12 oz
- Weak: mug
- Weak: handmade ceramic mug pottery mug coffee mug gift
- Good (image 1): Oatmeal-glazed stoneware mug with brown speckles and a rounded handle, shown from the side
- Good (image 2): Bottom of the speckled stoneware mug showing the unglazed clay foot and stamped maker's mark
- Good (image 3): Speckled oatmeal mug filled with coffee on a wooden table beside a folded linen napkin
Product: Sterling Silver Hammered Hoop Earrings, Small
- Good (image 1): Pair of small sterling silver hoop earrings with a hammered texture, on a white background
- Good (image 2): Hammered silver hoop earring worn on an earlobe, shown close up for scale
Product: Linen Wrap Dress, Rust, variant image
- Good: Rust-colored linen wrap dress with short sleeves and a tie waist, worn by a model, front view
Notice that each description would still make sense if someone heard it without seeing the page.
Step 4: Fill-in templates
Copy these patterns and swap in your details.
Front or main shot [Color] [material] [product type] with [one or two distinctive features], [angle or background]
Detail shot Close-up of [part of product] on the [product name], showing [texture, stitching, mark, clasp]
In-use or lifestyle shot [Product] [being worn / in use / styled] [where or how], [one detail that shows scale or context]
Variant shot [Product name] in [variant color or finish], [angle]
Packaging or group shot [Number] [products] [arranged how], [in packaging / with matching items]
Step 5: Test with one or two products first
Don't import the whole catalog on your first try.
- Make a small copy of your edited CSV that contains only the rows for one or two products. Keep the header row.
- Import it (steps below).
- Open those products in the admin. Check that the alt text appears on the right images and that titles, prices, descriptions, variants and inventory look unchanged.
If the result looks right, import the full file.
Step 6: Import the file
- Go to Products and click Import.
- Upload your edited CSV.
- Select the option to overwrite products with matching handles. Without it, Shopify won't update your existing products.
- Review the preview and confirm.
Read the wording next to the overwrite option carefully. With overwrite turned on, the values in your file replace what is in your store. If a column in your file is blank where your store has data, that data can be overwritten or cleared. This is the main reason to edit a full export rather than build a new file from scratch, and to change only the alt text column.
Large imports can take a while. Shopify will notify you when the import finishes.
Pre-import checklist
Run through this before you click import:
- [ ] I saved an untouched backup export.
- [ ] I edited a fresh export, not a file built by hand.
- [ ] I changed only the Image Alt Text column.
- [ ] Handles, Image Src and Image Position values are unchanged.
- [ ] My spreadsheet app did not reformat anything (watch for leading zeros dropped from SKUs or barcodes, and for long numbers turned into scientific notation).
- [ ] I saved the file as CSV with UTF-8 encoding, so accented characters and symbols survive.
- [ ] I tested the import on one or two products first.
- [ ] The overwrite option is selected, and I understand that blank values can replace existing data.
Common problems and fixes
- Alt text didn't appear. Check that the overwrite option was selected and that the Handle and Image Src values exactly match the export.
- Other product fields changed. Re-import the affected products from your backup file, then repeat with a cleaner edit.
- Strange characters in the descriptions. The file probably wasn't saved as UTF-8. Re-save it and re-import.
- The same alt text is on every image of a product. Go back and describe what each photo specifically shows.
When to do it by hand instead
If you only have a handful of images, editing in the admin is simpler and carries no import risk. Open the product, click each image and type the alt text. The CSV method pays off once you are dealing with dozens of images or more.
After it's done
Make alt text part of your listing routine. Write it at the same moment you upload a new product photo, and the backlog never builds up again.
Browse the Quillwork shop