Auto-Set Image Alt Text from Filename on Upload

Alt text on images serves two purposes: it provides context to screen readers for accessibility, and it tells search engines what an image depicts when they can’t interpret visual content. WordPress requires editors to add alt text manually for every image they upload, and in practice, on most sites, the vast majority of images have no alt text at all because the step is easy to skip and there’s no enforcement.

This snippet addresses the problem at the source by automatically populating alt text from the image filename the moment a file is uploaded. A file named blue-merino-wool-sweater.jpg gets an alt text of “Blue Merino Wool Sweater” automatically. Editors can still override it manually in the Media Library, but at least there’s always a starting value rather than an empty field.

The Code

Add this to your functions.php or a site-specific plugin. It hooks into add_attachment, which fires immediately after any file is uploaded to the Media Library.

How the Alt Text Is Generated

The snippet uses get_attached_file() to retrieve the full server path to the uploaded file, then pathinfo() with PATHINFO_FILENAME to extract just the filename without its extension. This gives you the raw filename slug as WordPress stored it, for example blue-merino-wool-sweater.

str_replace() converts both hyphens and underscores to spaces, since both are common word separators in filenames. ucwords() capitalises the first letter of each word, producing a human-readable label suitable for alt text. The result is passed through sanitize_text_field() before being saved as post meta.

The Skip Checks

Two guards prevent the snippet from overwriting existing data. The first checks wp_attachment_is_image(), only image files get alt text, not PDFs, videos, or other media. The second checks whether alt text is already set under the _wp_attachment_image_alt meta key. This prevents the snippet from overwriting alt text that was set programmatically by another tool or a previous upload workflow.

Filename Quality Matters

The quality of the generated alt text depends entirely on the quality of the filename. A file named IMG_4823.jpg will generate alt text of “Img 4823”, which is useless. A file named homepage-hero-woman-laptop.jpg will generate “Homepage Hero Woman Laptop”, which is meaningfully descriptive. The snippet works best when paired with a file naming convention, educating clients and contributors to name files descriptively before uploading pays dividends in both SEO and accessibility.

Bulk Updating Existing Images

This snippet only affects images uploaded after it’s installed. To retroactively populate alt text for existing images that have empty alt fields, you can run a custom WP-CLI script or a one-time admin action that loops through all attachments, checks for missing alt text, and applies the same filename-to-alt-text logic. This is safe to run since the snippet already includes a guard that skips any image that already has alt text set.

functions.php

add_action( 'add_attachment', function( $attachment_id ) {
    // Only process images
    if ( ! wp_attachment_is_image( $attachment_id ) ) return;

    // Skip if alt text is already set
    if ( get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ) ) return;

    $filename  = pathinfo( get_attached_file( $attachment_id ), PATHINFO_FILENAME );

    // Clean the filename: remove hyphens/underscores, capitalise words
    $alt_text  = ucwords( str_replace( [ '-', '_' ], ' ', $filename ) );

    update_post_meta( $attachment_id, '_wp_attachment_image_alt', sanitize_text_field( $alt_text ) );
} );