Image File Naming Guide: Conventions, Automation, and Bulk Migration

Introduction

This guide covers practical image file naming conventions, how to automate renaming in upload pipelines (CMS, storage buckets), and how to migrate an existing image library without breaking indexed URLs. The UXR SEO Analyzer detects generic naming patterns site-wide, not just on individual images.

If you need the conceptual background first, see Image File Names Explained.

Recommended Naming Convention

[main-topic]-[specific-detail]-[optional-variant].[extension]

Examples:
gray-running-shoes-orange-sole.jpg
marketing-team-meeting-santiago-office.jpg
user-growth-chart-q3-2026.png

Technical Rules

• Always lowercase—Unix-style file systems are case-sensitive and user searches are almost always lowercase.
• Hyphens (-) to separate words, never underscores (_) on new files: hyphens are interpreted as spaces by search engines.
• Standard ASCII characters only: no accents, special characters, spaces, or symbols.
• Maximum 4-5 descriptive words; avoid names longer than 60-70 characters.
• Use the formal file type name when documenting (e.g., "a PNG file") instead of referring generically to the extension.

Automation in the Upload Pipeline

Normalization Script (Node.js)

function slugifyFilename(originalName, description) {
  const ext = originalName.split('.').pop().toLowerCase();
  const base = description
    .toLowerCase()
    .normalize('NFD').replace(/[̀-ͯ]/g, '') // strip accents
    .replace(/[^a-z0-9s-]/g, '')
    .trim()
    .replace(/s+/g, '-')
    .slice(0, 60);
  return `${base}.${ext}`;
}

// slugifyFilename('IMG_4382.JPG', 'Gray running shoes orange sole')
// -> 'gray-running-shoes-orange-sole.jpg'

Headless CMS Integration

Most headless CMSs (Contentful, Sanity, Strapi) support a pre-upload or asset transform hook where you can apply this normalization before persisting the file, forcing editors to describe the image at upload time.

Migrating an Existing Library

1. Audit: export a list of all current file names and classify which ones are generic (IMG_, DSC, screenshot, UUIDs).
2. Prioritize: focus first on images with Google Images traffic or image backlinks, since renaming them requires redirects.
3. Redirect: every renamed file needs a 301 redirect from the old URL to the new one so you don't lose accumulated indexing value.
4. Update internal references: find and replace every reference to the old file name in HTML, CSS, and image sitemaps.
5. Resubmit the image sitemap to Search Console after the migration.

Risks of Not Redirecting

If you rename an indexed file without a 301 redirect, Google will return a 404 for the old URL and will need to rediscover and reindex the image at the new URL from scratch, losing any ranking it had already earned in Google Images.

Migration Checklist

Step	Suggested tool
List current files	Crawling script (Screaming Frog, custom script)
Detect generic names	Regex over patterns like IMG_\d+, DSC\d+, UUIDs
Generate redirects	CSV mapping → 301 rules at the server/CDN
Verify post-migration	Search Console → Image coverage

Convention by Content Type

Not every image on the site is the same, and the naming convention can vary slightly by content type, while always keeping lowercase, hyphens, and standard ASCII as the common rules:

Content type	Suggested pattern	Example
E-commerce product	[brand]-[product]-[color-variant].[ext]	nike-running-shoes-gray.jpg
Blog featured image	[topic]-[main-keyword].[ext]	image-seo-cdn-optimization.jpg
UI icon or asset	icon-[function-name].[ext]	icon-shopping-cart.svg
Team/brand photo	[name]-[role]-[year].[ext]	maria-gonzalez-director-2026.jpg

Automated Validation in CI/CD

To keep generic names from creeping back into the assets repository, add a validation step in the continuous integration pipeline that rejects files not matching the expected pattern:

const GENERIC_PATTERN = /^(img_|dsc_|screenshot|image\d*|photo\d*|untitled)/i;
const VALID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.(jpg|jpeg|png|webp|avif|svg)$/;

function validateFilename(filename) {
  if (GENERIC_PATTERN.test(filename)) {
    throw new Error(`Generic file name rejected: ${filename}`);
  }
  if (!VALID_PATTERN.test(filename)) {
    throw new Error(`File name doesn't follow the convention: ${filename}`);
  }
  return true;
}

Wire this validation in as a pre-commit hook or as part of the CI job that processes new assets uploaded to the repository, so you catch the problem before the image reaches production.

Multilingual Considerations

For bilingual or multilingual sites, it's tempting to name the file in the language of the content where it's first used, but this creates inconsistency when the same image gets reused in another language. The recommended practice is to name the physical file in English or in a neutral language shared by the team (for example, running-shoes-gray.jpg), and reserve localization for the alt attribute, which should be translated per language.

Bulk Audit With a Crawling Script

For sites with thousands of already-published images, a manual file-by-file audit isn't practical. The following approach combines a crawler with classification rules to generate a prioritized report:

const results = { generic: [], underscored: [], keywordStuffed: [], ok: [] };

for (const imageUrl of allImageUrls) {
  const filename = imageUrl.split('/').pop().split('?')[0];
  if (/^(img_|dsc_|screenshot|untitled)/i.test(filename)) {
    results.generic.push(imageUrl);
  } else if (/_/.test(filename)) {
    results.underscored.push(imageUrl);
  } else if ((filename.match(/-/g) || []).length > 6) {
    results.keywordStuffed.push(imageUrl);
  } else {
    results.ok.push(imageUrl);
  }
}

console.table({
  generic: results.generic.length,
  underscored: results.underscored.length,
  keywordStuffed: results.keywordStuffed.length,
  ok: results.ok.length,
});

Prioritize fixing images in results.generic first, since they carry no semantic signal at all, followed by results.underscored on new or low-traffic files where renaming doesn't require a complex redirect.

Coordinating With the Editorial Team

Technical automation only solves half the problem: if content editors keep uploading camera-named files without describing the image, the problem keeps coming back. Document the naming convention in the team's style guide, and if your CMS allows it, add a required "file description" field to the upload form that gets used to automatically generate the final name via the normalization script.

File Naming and Duplicate Content Across Domains

If the same image is served from multiple hostnames or subdomains you own—for example, a CDN mirror and the original origin—search engines may pick one copy as the canonical version, which may not be the one you intended to rank. Keeping a single, consistent file name across every copy (rather than letting each environment generate its own) makes it easier to later declare a canonical image via an image sitemap or consistent linking, and avoids the slower crawling and indexing that duplicated hostnames can cause.

Handling Legacy File Names Without a Full Rewrite

Not every site can afford a full rename-and-redirect project immediately. A pragmatic middle ground is to enforce the new convention only for newly uploaded assets going forward, while leaving historically indexed images untouched until they naturally get replaced or the page they belong to is redesigned. This avoids the redirect overhead and ranking risk of a bulk rename while still stopping the problem from growing, and gives you a natural cutoff date to measure improvement from.

Related Articles

• Image File Names Explained - Fundamentals
• Alt Text Implementation Guide - Alt text in depth
• URL Structure Optimization Guide - Principles that also apply to file names

---

References

1. Google Developers - Filenames and file types
2. Google Search Central - 1000 Words About Images
3. Google Search Central - SES Chicago - Using Images