---
title: "Name image files for what they show · Agent Wranglers"
url: https://agentwranglers.se/playbook/seo/images-and-video/descriptive-image-names
id: SEO-65
level: Recommended
updated: 2026-10-22
tokens: 762
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Name image files for what they show

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Images and video](https://agentwranglers.se/playbook/seo/images-and-video.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: SEO-65
- Level: Recommended
- Chapter: [Images and video](https://agentwranglers.se/playbook/seo/images-and-video.md)
- Rule: Give every content image a short file name that says what it shows, in lowercase words joined by hyphens. Place it with an `<img>` element near the text it belongs to, never as a CSS background.
- Check: A build test lists every image in the main content. Each is an `<img>` with a `src`, and no file name matches `^(img|image|dsc|pxl|photo|screenshot)[-_ ]?\d+` or has fewer than two words.
- How: Google asks for short, descriptive file names instead of names such as `IMG00023.JPG`, and says it does not index images set in CSS. It also looks at the text around an image, so put the photo next to the paragraph it explains. Use a format Google indexes, such as JPEG, PNG, WebP, AVIF or SVG. With `srcset` or `<picture>`, keep a fallback in `src`. Make the files small as [Send small, modern images](https://agentwranglers.se/playbook/website/performance/image-optimization.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
const GENERIC = /^(img|image|dsc|pxl|photo|screenshot)[-_ ]?\d+/i;
const badNames = images.map(src => src.split('/').pop().replace(/\.\w+$/, ''))
  .filter(name => GENERIC.test(name) || name.split('-').length < 2);
assert.deepEqual(badNames, []);
```

### Python example

```python
import re
from pathlib import PurePosixPath

GENERIC = re.compile(r"^(img|image|dsc|pxl|photo|screenshot)[-_ ]?\d+", re.I)
bad_names = [PurePosixPath(src).stem for src in images
             if GENERIC.match(PurePosixPath(src).stem) or len(PurePosixPath(src).stem.split("-")) < 2]
assert bad_names == []
```

## Sources

- [Google Search Central – Image SEO best practices](https://developers.google.com/search/docs/appearance/google-images)

## Related rules

- WEB-38 [Send small, modern images](https://agentwranglers.se/playbook/website/performance/image-optimization.md) in Website

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/seo/images-and-video/descriptive-image-names">Agent Wranglers SEO playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Describe the image in its alt text](https://agentwranglers.se/playbook/seo/images-and-video/alt-text-for-search.md)
- [Images and video](https://agentwranglers.se/playbook/seo/images-and-video.md)