How to Import Alt Text CSV to WordPress, Shopify, and Contentful

After ConvertYard's alt text generator has processed all the images on your site, you will receive a CSV file with two columns: filename and alt_text. In this tutorial, we'll explain how you can import these descriptions into your Content Management System (CMS). The tutorial applies to WordPress, Shopify, Contentful, and many other CMS.

Generate alt text for 100+ images at once — runs in your browser →

The CSV format

Open the exported CSV file in your favorite spreadsheet and review the contents before importing it into your CMS.

filename,alt_text
product-blue-hoodie.jpg,"Blue pullover hoodie with kangaroo pocket, front view"
team-photo-2024.jpg,"Seven people standing in an office lobby smiling at the camera"
hero-banner.png,"Close-up of a hand holding a coffee cup over a wooden table"

Context – the images the AI does not get. Be aware that the AI can only describe what it can see and therefore miss the all-important context for the image on your site. For example, an image of a blue hoodie needs the product name added to the description, i.e., "Eastfield Classic Hoodie in Navy, front view". Take 10 minutes to scan through the descriptions for the brand and product context that is obviously missing.

Check the generated descriptions for errors. Very dark, blurred, or mostly text images like screenshots or infographics can generate poor results. Fix these before importing.

WordPress

Option 1: Media Library (manual, small batches)

For fewer than 20 images, the Media Library is the fastest route:

1. Go to Media → Library, change to list view by clicking on the "switch to list view" link at top of page.
2. Click the image to open the Attachment Details page for that image.
3. Find the Alt Text field on the right side.
4. Paste in the alt text from the relevant row of your spreadsheet, click Update.

This works great for small numbers of images but as you get up into the teens and beyond of images then one of the following methods is likely to be faster.

Option 2: WP All Import (plugin, bulk)

WP All Import is a powerful WordPress plugin that can be used to import information from CSV files into WordPress post meta fields. It can be used to add the image alt text to each attached image and store it in the _wp_attachment_image_alt custom field.

1. Install and activate WP All Import.
2. Under All Import, click New Import and upload your alt text CSV.
3. Set the import type to Custom Post Type → Attachment.
4. Map the CSV fields to the fields in the WordPress Import process. This would be filename to attachment identifier (which is the post title or file URL) and then alt_text to the custom field for the image alt text _wp_attachment_image_alt.
5. Run the import.

You must match images by filename in this approach, so you need to ensure that the filenames in your spreadsheet match exactly those in the Media Library. That means you must reconcile any differences in the spreadsheet prior to using this approach if you have changed the filename of any images when uploading them to the WordPress Media Library.

Option 3: WP-CLI (developer, any batch size)

If you have SSH access to your server and WP-CLI installed, this is the most reliable approach for large libraries:

# Find the attachment ID for a given filename
wp post list --post_type=attachment --name="product-blue-hoodie" --fields=ID

# Update alt text for attachment ID 142
wp post meta update 142 _wp_attachment_image_alt "Eastfield Classic Hoodie in Navy, front view"

For bulk updates, write a short bash script that reads your CSV and runs wp post meta update for each row. Here's a minimal example:

#!/bin/bash
# update-alt-text.sh
# Run from your WordPress root: bash update-alt-text.sh alt-text.csv

while IFS=, read -r filename alt_text; do
  # Skip header row
  [[ "$filename" == "filename" ]] && continue

  # Strip quotes from alt_text if present
  alt_text="${alt_text//\"/}"

  # Get attachment ID by filename (strips extension for slug matching)
  slug="${filename%.*}"
  id=$(wp post list --post_type=attachment --name="$slug" --fields=ID --format=csv | tail -1)

  if [[ -n "$id" && "$id" != "ID" ]]; then
    wp post meta update "$id" _wp_attachment_image_alt "$alt_text"
    echo "Updated $filename (ID $id)"
  else
    echo "Not found: $filename"
  fi
done < "$1"

Run it with: bash update-alt-text.sh alt-text.csv

Shopify

Alt text for Shopify product images is stored in a field that is mapped to the Image Alt Text column in the product CSV.

Via product CSV import

1. Export all the products from the Products page in Shopify using the Export feature and choose CSV as the file type. Open this CSV in Excel or Google Sheets.
2. Open your CSV in Excel or Google Sheets. Locate the columns Image Src and Image Alt Text.
3. Open your alt text CSV from ConvertYard alongside this file.
4. Match rows by filename: the Image Src column contains the full URL — the filename is the last segment (e.g., https://cdn.shopify.com/.../product-blue-hoodie.jpg).
5. Paste the corresponding text from the alt_text CSV file into the Image Alt Text column.
6. Save that CSV and then go to Products → Import and upload that file.

Note: This tip uses VLOOKUP / XLOOKUP to match filename in Shopify CSV with corresponding alt text in your ConvertYard CSV.

=IFERROR(
  VLOOKUP(
    RIGHT(
      B2,
      LEN(B2) - FIND("✦", SUBSTITUTE(B2, "/", "✦", LEN(B2) - LEN(SUBSTITUTE(B2, "/", ""))))
    ),
    AltTextSheet!A:B,
    2,
    0
  ),
  ""
)

(This code snippet extracts the filename from the full URL of a Shopify CDN hosted image, and looks that up in your alt text sheet.)

Via Shopify Admin API

For developers managing large catalogs programmatically:

// Update image alt text via Shopify Admin API (REST)
const response = await fetch(
  `https://${shop}/admin/api/2024-01/products/${productId}/images/${imageId}.json`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Access-Token': accessToken,
    },
    body: JSON.stringify({
      image: { id: imageId, alt: altText },
    }),
  }
)

Loop over your CSV rows, look up the image ID by filename using the GET /products/{id}/images.json endpoint, then PUT the updated alt text.

Contentful

All images in Contentful are stored as Assets. An asset has a description field. When you then include an asset in a template, this description field is used as alt text for the images in the templates.

Via the web app (small batches)

1. Go to Content → Media.
2. Find the asset by name (use the search bar).
3. Click the asset to open it.
4. Update the Description field with the corresponding alt text from the CSV file.
5. Click Publish.

Via the Contentful Management API

For bulk updates, the Management API is the right tool:

const contentful = require('contentful-management')

const client = contentful.createClient({ accessToken: 'YOUR_CMA_TOKEN' })
const space = await client.getSpace('YOUR_SPACE_ID')
const environment = await space.getEnvironment('master')

// altTextMap: { 'filename.jpg': 'Description text', ... }
// Build this map by parsing your CSV

for (const [filename, altText] of Object.entries(altTextMap)) {
  const assets = await environment.getAssets({ 'fields.file.fileName': filename })

  if (assets.items.length === 0) {
    console.log(`Not found: ${filename}`)
    continue
  }

  const asset = assets.items[0]
  asset.fields.description = asset.fields.description ?? {}
  asset.fields.description['en-US'] = altText

  const updated = await asset.update()
  await updated.publish()
  console.log(`Updated: ${filename}`)
}

Install the SDK with npm install contentful-management, replace the token and space ID, and run with Node.js.

Webflow

Webflow does not currently support a bulk import of alt text via a CSV file. This is something that the team is exploring but as of mid-2025 there is no way to achieve this.

• Manual: Select each image element in the Designer and update the Alt Text field in the Settings panel.
• CMS Items in Collections: You can first export a CSV file from CMS items in Collections. Then add or modify the required info in the corresponding CSV column, and import the updated file back into Webflow.
• Webflow API: Similar as with the Contentful API above, update the CMS item fields programmatically using the Webflow Data API.

Squarespace

You can add alt text to individual images in Squarespace by editing the image in the Page Editor for a specific page where that image appears and updating the Filename / Alt text field.

1. Click an image block to select it.
2. Click the pencil icon to edit.
3. Under the image, find the Filename / Alt text field.
4. Update it with your CSV value.

For large Squarespace sites, importing alt text via CSV is not currently possible. To help manage your images, you may wish to move to another web design platform or website builder that offers more flexibility for making bulk changes to images, and then see if their API can be used by yourself or your developer to update the images' alt text, or contact the Support Team to inquire about using the Webflow API.

Custom CMS or database

This will typically be a one off SQL command that will update the images in your custom CMS or database. The SQL command will depend on the schema of your CMS, and the following example is for a typical WordPress install:

-- Update image alt text in a custom attachments table
UPDATE attachments
SET alt_text = 'Your alt text here'
WHERE filename = 'product-blue-hoodie.jpg';

Or for a batch update using a temp table:

-- Create a temp table and bulk-load your CSV
CREATE TEMP TABLE alt_imports (filename TEXT, alt_text TEXT);
COPY alt_imports FROM 'YOUR_LOCAL_CSV_PATH' DELIMITER ',' CSV HEADER;

-- Update main table
UPDATE attachments a
SET alt_text = i.alt_text
FROM alt_imports i
WHERE a.filename = i.filename;

For systems using an ORM, write a migration script that reads the CSV and iterates over rows using your ORM's update method.

Review checklist before importing

Run through this before pushing alt text to production:

• Product names included — AI doesn't know "Eastfield Classic Hoodie" (add in the product name to the product images).
• Branded terms correct — Company names, proper nouns, and product model numbers often are missing or incorrect in generated descriptions.
• "Image of" is redundant — Screen readers automatically announce the word "image". Remove this from your import list.
• Text-in-image handled — This ensures that any important text within images (such as price tags, product labels or signs) is included within the generated alt text and may help the AI avoid missing key information.
• Decorative images marked — Decorative images in the batch of images to be uploaded need to be marked in the CSV for uploading so that no description is added to these images, i.e., these images need to have alt="" in HTML.
• Spot-check 10 entries — Manually verify 10 descriptions against their corresponding images before uploading the rest of your batch.