How to add alt text in WordPress (and do it in bulk)

WordPress runs a large share of the web, which means a large share of the web’s missing alt text lives in a WordPress media library. If you have ever inherited a site with two thousand images and no descriptions, this guide is for you.

First the mechanics, then the part nobody tells you: how to do it without losing a week.

Where WordPress actually stores alt text

This trips people up, so let’s be precise. WordPress stores the alt text on the media library item, not on the place you inserted the image. That has two consequences:

• Set the alt text once in the media library, and every future insertion of that image inherits it.
• But alt text you type into a block is stored on that block, and overrides the library value for that one placement. So the same image can have different alt text on two pages, which is usually what you want.

The upshot: for a reusable image (a logo, an icon), set it in the media library. For a content image whose meaning depends on the page, set it on the block.

Adding it in the block editor

1. Click the image block.
2. Open the block settings sidebar (the gear icon).
3. Under Settings → Alternative text, type the description.

That is the whole flow. The friction is not the interface — it is that you have to do it for every image, and the reward is invisible, so it gets skipped.

Adding it in the media library

1. Media → Library, click an image.
2. Fill in the Alternative Text field in the attachment details panel.
3. It saves automatically.

This is the right place for images used in multiple spots, because the value propagates.

The Title, Caption and Description fields are not alt text

WordPress shows four fields on every attachment, and three of them are decoys for accessibility:

• Alternative Text — the real alt attribute. The only one screen readers and search engines read as alt.
• Caption — visible text shown under the image. Useful, but seen by everyone, so not a replacement for alt.
• Description — shown only on the attachment page, which most sites never use.
• Title — becomes a tooltip; largely ignored by assistive tech. Do not put your alt text here.

If you have been diligently filling in the Title field thinking it was alt text, you have been writing tooltips. It happens constantly.

What to actually write

The rules are the same everywhere, and we cover them in depth in how to write good alt text. The short version:

• Describe the image’s function on the page, not just its contents.
• Do not start with “image of” — the screen reader already said that.
• Decorative images (dividers, background flourishes) get an empty alt, which in WordPress means leaving the Alternative Text field blank and not relying on the theme to invent one.
• Do not stuff keywords. It does nothing for SEO and makes the page hostile to the people alt text is for.

The bulk problem

Everything above is fine for the next ten images you add. It does nothing for the two thousand already sitting in the library with the field blank.

And clicking through two thousand attachments is not a plan — it is how the task gets abandoned at image forty. So the realistic approach is to work outside the WordPress admin:

1. Export the list of images. Any “list media” or export plugin will give you a CSV of your media URLs and their IDs. If you are comfortable with the database, the wp_posts table (attachments) has what you need.
2. Generate a draft for each one. Run the image URLs through an AI pass to get a factual description of every image at once. PicsTag does this in your browser — feed it the CSV, and it exports a CSV of descriptions keyed on your media IDs. Nothing is uploaded.
3. Edit the drafts. This is the part that stays human: fix the images that carry meaning (charts, screenshots, product shots), and blank out the decorative ones. Most drafts will be fine as-is.
4. Import them back. A bulk-edit plugin that accepts a CSV of attachment_id → alt_text writes them all in one pass. Alternatively, WP-CLI:

   wp post meta update <id> _wp_attachment_image_alt "Your alt text"

   in a loop over your CSV.

The key mental shift: WordPress is where the alt text lives, but it is the worst place to produce it in bulk. Produce it outside, import it back.

WordPress-specific mistakes to avoid

• Trusting a plugin that “auto-generates” alt text and calls it done. The generation is the easy 80%; the editing is the important 20%. A plugin that writes alt text and never asks you to review it is filling your site with plausible-but-sometimes-wrong descriptions, unreviewed.
• Letting the theme fall back to the title or filename. Some themes output the image title as alt if the alt is empty. That turns your decorative images into alt="header-bg-final-v2", read aloud. Check your theme.
• Forgetting images added by page builders. Elementor, Divi and friends often store images in their own data, not the standard block, so a media-library sweep can miss them. Audit the rendered pages, not just the library.

The one check that matters

After you have done all this, do not trust the coverage number. Turn on a screen reader — VoiceOver on Mac, NVDA on Windows, both free — and navigate one of your real pages with the screen off. You will hear, in about thirty seconds, whether your alt text is useful or noise. No plugin dashboard tells you that.