How to Name Website Image Files for SEO

Use a short, accurate description of what the image shows. Write it in lowercase, separate words with hyphens, and keep the extension aligned with the actual file format. For example, use black-kitten-on-window.jpg instead of IMG00023.JPG.

A filename gives search engines only a light clue. The image’s subject, surrounding page copy, caption, title, and especially useful alt text provide more context. Google’s image guidance recommends short, descriptive filenames and warns against generic names such as image1.jpg, pic.gif, and 1.jpg.

1. The recommended filename formula

Build filenames from the visible subject, followed by one or two true differentiators when they help identify the image:

subject-differentiator-view-or-use.extension

Part	What to include	Example
Subject	The main visible object, person, place, or action	`ceramic-coffee-mug`
Differentiator	Color, model, variant, location, or other visible distinction	`blue`
View or use	Front view, detail, installation, cart, or another useful context	`front`
Extension	The real encoded format	`.jpg`

Examples:

blue-ceramic-mug-front.jpg
wordpress-media-library-upload.png
running-shoes-cart.webp
section-divider.svg

2. Use lowercase letters and hyphens

Lowercase ASCII letters, numbers when needed, and hyphens make URLs readable and portable. Google’s URL guidance recommends hyphens as word separators; search engines generally interpret hyphens as spaces and may not recognize underscores in the same way.

blue-ceramic-mug-front.jpg

Avoid:

Underscores: blue_ceramic_mug.jpg
Spaces that become encoded characters: blue%20ceramic%20mug.jpg
Mixed case: BlueCeramicMug.JPG
Punctuation and symbols: mug(1)&final!.jpg
Long keyword strings: best-blue-ceramic-coffee-mug-buy-cheap-online.jpg

Keep names readable. A filename does not need every possible keyword; it needs an accurate description.

3. Filename length: short, specific, maintainable

There is no official character limit that makes a filename “SEO-ready.” Use enough words to distinguish the image from similar files, then stop. Two to six descriptive words usually work for ordinary editorial and product images.

Prefer:

ceramic-coffee-mug-blue.jpg

Over:

ceramic-coffee-mug-blue-product-photo-front-angle-kitchen-table-2026.jpg

Dates belong in a filename only when they identify the subject, such as 2026-annual-report-cover.pdf. Do not add dates merely because the file was uploaded that day.

4. Filename versus alt text, captions, and page copy

The filename is not a replacement for alt text. Google describes alt text as the most important image metadata attribute because it helps explain an image to people who cannot see it and to search systems. Write alt text for the image’s context, not as a list of ranking terms.

Asset	Example	Purpose
Filename	`blue-ceramic-mug-front.jpg`	Readable file and URL clue
Alt text	“Blue ceramic mug, front view”	Accessible description
Caption	“The blue mug is part of the spring tableware collection.”	Visible editorial context
Page copy	Product or article text near the image	Explains relevance and purpose

For a decorative flourish, use the accessibility pattern your site follows; an empty alt attribute can be correct when the image conveys no information. For a linked image, make the alt text describe the destination or action, such as “Add running shoes to your cart.” Google can use linked-image alt text as anchor context.

5. Should you add keywords?

Add a keyword only when it naturally and accurately describes the visible subject. A product image named blue-ceramic-mug.jpg is useful because those words identify the object. Repeating a phrase or adding terms the image does not show creates misleading metadata and makes asset management harder.

Good keyword use

vegan-chocolate-chip-cookie.jpg

Keyword stuffing

best-cheap-vegan-cookie-dessert-buy-online-recipe.jpg

6. Choose the extension that matches the file

Keep the filename extension consistent with the encoded format. Common web image formats include JPEG, PNG, WebP, SVG, and AVIF. Renaming photo.png to photo.jpg does not convert the file; it can cause incorrect content types, broken previews, or processing failures.

Format	Typical use
JPEG	Photographs and complex images
PNG	Transparency, screenshots, and lossless graphics
WebP	Web delivery when your stack supports it
AVIF	Modern compressed delivery when supported by your pipeline
SVG	Vector logos, icons, and illustrations

7. Naming galleries and repeated variants

Use meaningful differentiators instead of unexplained sequences whenever possible:

running-shoes-side.jpg
running-shoes-sole.jpg
running-shoes-on-trail.jpg

If a sequence is necessary for ordering or automation, combine it with a subject:

team-retreat-01.jpg
team-retreat-02.jpg
team-retreat-03.jpg

Keep one consistent convention across the directory. When the same image is reused, retain one stable image URL where practical instead of creating duplicate files with slightly different names.

8. Localization and non-ASCII names

For multilingual sites, translate filenames when the localized URL structure and publishing workflow support it. Use URL encoding correctly, avoid characters that your CDN or CMS normalizes unpredictably, and apply the same separator and casing rules in every language. A translated filename is useful only if it remains maintainable for editors and developers.

9. A practical renaming workflow

List the images that will be published.
Identify the visible subject and the page or component where it appears.
Choose one or two true differentiators.
Convert the words to lowercase and join them with hyphens.
Preserve the real extension.
Write contextual alt text separately.
Update references, responsive-image variants, manifests, and CMS fields.
Check that old URLs redirect or remain available when changing already-indexed assets.
Confirm the server returns the correct MIME type and that the image loads at its final URL.

Bulk rename with Python

from pathlib import Path
import re

folder = Path("images")

def slugify(text):
    text = text.lower()
    text = re.sub(r"[^a-z0-9]+", "-", text)
    return text.strip("-")

for path in folder.iterdir():
    if not path.is_file():
        continue
    # Replace this mapping with labels from your CMS or asset spreadsheet.
    label = path.stem.replace("_", " ")
    new_name = slugify(label) + path.suffix.lower()
    target = path.with_name(new_name)
    if target != path and not target.exists():
        path.rename(target)
        print(f"{path.name} -> {target.name}")

Bulk rename with Node.js

import { readdir, rename } from 'node:fs/promises';
import { join, extname, basename } from 'node:path';

const folder = 'images';
const slugify = (value) => value.toLowerCase()
  .replace(/[^a-z0-9]+/g, '-')
  .replace(/^-|-$/g, '');

for (const file of await readdir(folder)) {
  const extension = extname(file).toLowerCase();
  const label = basename(file, extname(file)).replaceAll('_', ' ');
  const next = `${slugify(label)}${extension}`;
  if (next !== file) {
    try {
      await rename(join(folder, file), join(folder, next));
      console.log(`${file} -> ${next}`);
    } catch (error) {
      console.error(`Could not rename ${file}: ${error.message}`);
    }
  }
}

10. What to check before publishing

The name describes what is visibly present.
Words are lowercase and separated by hyphens.
There are no generic camera names or meaningless IDs.
The extension matches the encoded format.
Alt text describes the image in its page context.
Captions and nearby copy add useful context where appropriate.
Linked images describe their destination or action.
Duplicate variants follow one naming convention.
Localized versions follow the site’s URL and encoding rules.
Renaming an existing public asset will not leave broken references.

11. Troubleshooting common problems

Problem	Likely cause	Fix
The image returns 404	A reference still uses the old filename or case	Update every reference and verify case-sensitive production paths.
The browser downloads the file instead of displaying it	Wrong MIME type or extension	Serve the actual format with the matching content type.
Renaming did not change SEO results immediately	Filename is only one light signal and recrawling takes time	Keep page context, alt text, captions, and image quality useful; do not expect a filename alone to change rankings.
Alt text repeats keywords awkwardly	Filename was copied directly into accessibility text	Rewrite alt text as a natural description for the person using the page.
Two files overwrite each other	Different original names normalize to the same slug	Add a true differentiator or a controlled sequence and detect collisions before renaming.
Old indexed URLs break	A public asset was renamed without a migration	Update sitemaps and references and preserve the old URL or redirect it where your delivery layer supports redirects.
CMS strips or changes the name	Upload or storage rules normalize filenames	Inspect the final stored URL and adjust the naming convention to the CMS’s rules.

12. Performance, reliability, and cost

Descriptive filenames add almost no processing cost, but a bulk migration can create operational work. Rename before upload when possible, because changing URLs later requires reference updates, cache invalidation, and checks for old links. Keep names short to reduce URL length, and use your normal image resizing and compression pipeline; a descriptive filename does not make an oversized image fast.

For large libraries, automate slug generation, collision detection, extension preservation, and a report of old-to-new paths. Review generated names before publishing so automation does not assert a subject the image does not show.

13. Or skip the browser setup

If your workflow needs screenshots of web pages before naming or cataloging them, ScreenshotNeo returns a clean PNG, JPEG, WebP, or PDF from one request. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('shot.webp', buffer);

ScreenshotNeo also supports full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching with a chosen TTL, signed links, asynchronous jobs, signed webhooks, bulk capture of up to 100 URLs per call, usage reporting, an OpenAPI specification, and an MCP server with take_screenshot, get_page_info, and capture_pdf for AI clients.

There are 1,000 screenshots per month free with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.

14. FAQ

Do hyphens or underscores work better?

Use hyphens. Google’s filename guidance says search engines interpret hyphens as spaces and generally do not recognize underscores the same way.

Does renaming an image guarantee higher rankings?

No. A descriptive filename supplies a light clue. Page text, alt text, captions, image content, and technical delivery also matter.

Should every filename contain a target keyword?

No. Include a keyword only when it accurately describes the visible subject and fits the page context.

How should decorative images be named?

Use a maintainable descriptive name for your asset library, but do not add search-targeted alt text when the image is purely decorative.

Should I rename files that are already published?

Rename when the benefit justifies migration work. Preserve or redirect old URLs, update references, and check caches and sitemaps before removing the old path.

Can I use numbers in filenames?

Yes, when they identify a real variant, sequence, model, or date. Avoid unexplained numbers that make the library harder to maintain.