Writing an Image Naming Convention Your Whole Team Will Actually Follow
Google's filename guidance is one sentence. Turning it into a convention that survives twelve people, three CMSes and four years is the real work. A token-based spec, the rules that make it enforceable, and how to retrofit a site that never had one.
Google's guidance on image filenames fits in a sentence: use descriptive filenames. Everyone agrees with it. Almost nobody has a site where it is consistently true, because a site's image library is not written by one person on one day. It is written by a marketer in a hurry, a developer scripting an import, an agency handing over assets, and a phone that names things IMG_4021.
A naming rule tells you what a good filename looks like. A naming convention is the thing that makes good filenames happen without anyone thinking about it. The gap between the two is where most image libraries go wrong, and closing it is a governance problem more than an SEO one.
What the convention has to survive
Before writing a spec, it helps to be honest about what will attack it.
Uploads from mobile arrive with camera codes. Design tools export names like Frame 12@2x.png. Stock downloads arrive as a vendor ID and eight digits. A CMS may lowercase filenames, or replace spaces with hyphens, or append a numeric suffix on collision, or do none of those. A CDN may add a transformation suffix. And a year from now someone will bulk-upload two hundred files from a client folder without reading anything.
A convention that only works when a careful person applies it by hand is not a convention. It is a preference.
The token model
The most durable approach is to stop thinking of a filename as a sentence and start thinking of it as an ordered list of tokens, most specific first:
subject → qualifier → context → variant
Concretely:
- bench-vise-workshop.webp
- bench-vise-workshop-closeup.webp
- transit-van-loading-arlington.webp
Specific-first matters because filenames get truncated in file lists, in CMS pickers and in link previews, and because it groups related assets together alphabetically. Sorting a directory where every bench-vise file sits next to every other bench-vise file is useful. Sorting a directory by the word "workshop", where a hundred unrelated things happen to be in a workshop, is not.
Rules that go with the model:
| Rule | Do | Don't |
|---|---|---|
| Case | all lowercase | Bench-Vise.webp |
| Separator | hyphens only | bench_vise.webp, bench vise.webp |
| Stop words | omit | a-bench-vise-in-the-workshop.webp |
| Length | 3 to 6 tokens | one-word or full-sentence names |
| Camera codes | never keep | IMG_4021.webp |
| Dates | omit | 2026-08-bench-vise.webp |
| Dimensions | omit | bench-vise-1920x1080.webp |
| Version | only when the file can change | bench-vise-v2.webp is fine |
| Location | only when the image is of that place | a city token on a studio stock photo |
The hyphen-versus-underscore point is the only one with a documented search rationale, and it is worth writing down precisely because it is the rule people most often get wrong out of habit from code, where underscores are normal.
The date rule is worth defending because it looks helpful. Dates in filenames answer a question almost nobody asks, they make otherwise-identical assets look different from each other, and they push the descriptive tokens further right where truncation eats them. Upload dates belong in the CMS, not the URL.
Where the location token gets abused
The temptation on a local business site is to append a city to every image, on the theory that more mentions of the city help. This is the filename version of stuffing alt text, and it produces filenames that are actively false: a stock interior labelled as a Fort Worth workshop when the photograph was taken in a studio somewhere else entirely.
Use the location token when the image depicts that location. A real van outside a real address, a completed job, a storefront. Otherwise leave it out. If the goal is to make an image carry a geographic claim, GPS coordinates written into the file's EXIF data do that job explicitly rather than by implication, and they do it in a field that was designed for exactly this purpose.
Making it enforceable
A convention becomes real when a machine checks it. The shape of the check matters less than its position: it has to run at the moment the file enters the system, because that is the only moment anyone is willing to rename anything.
A single expression catches the great majority of violations. Match against lowercase alphanumeric tokens joined by hyphens, two to six of them, with an approved extension, and reject everything else. That one pattern rejects uppercase, spaces, underscores, single-token names, over-long names and unexpected extensions in one pass.
Add a small blocklist for the patterns that slip past a generic rule, because they are technically well-formed but meaningless: img, dsc, screenshot, frame, untitled, final, copy, and your stock vendor's ID prefix. Between the pattern and the blocklist you have covered nearly every real-world failure.
Where the check lives depends on the stack. A build-time lint step works for repository assets. A CMS upload hook or a validation rule works for editorial images. An agency handing over a folder can be given the expression itself as part of the brief, which is far more effective than a paragraph of prose about being descriptive.
For images produced by a generation tool, the convention can be applied before the file exists rather than validated afterwards. That is the argument for having filenames, alt text and metadata written at generation time: a file that is born compliant never needs a lint rule. It is also why it pays to define the checkpoints worth running before you commit an image as an explicit short list rather than a vague intention to look at things properly.
What the CMS will do to your filename anyway
A convention has to be written knowing that the platform gets the last word, and each platform interferes differently. Establishing what yours does takes one test upload and saves a lot of confusion later.
Most systems lowercase the name and convert spaces to hyphens, which is convenient because it means a merely careless filename usually survives in a usable state. The behaviours that matter are the ones that alter the string in ways you did not intend.
Collision handling is the common one. Upload a second file with a name already in use and most platforms append a numeric suffix rather than refusing, which means the fifth photograph of a bench vise quietly becomes a name with a trailing number that describes nothing. This is an argument for making the descriptive tokens distinctive enough that collisions are rare, rather than relying on the platform to disambiguate for you.
Character handling is the second. Accented characters, ampersands and apostrophes are variously stripped, transliterated or percent-encoded, and a percent-encoded URL is legible to a machine and unreadable to a person. Restricting the convention to plain lowercase alphanumerics avoids the whole category.
The third is version parameters and transformation suffixes appended by the platform or its CDN. These are usually correct behaviour and nothing to fight, but they do mean the served URL is longer than what you uploaded and is not permanently stable. Any external process that stores image URLs needs to tolerate that.
Folders, and why they matter less than people think
Path structure is a weaker signal than the filename, but it shapes everything you do afterwards: auditing, sitemap generation, migration, permissions and cleanup.
Group by section or content type rather than by date. Date folders make it impossible to find anything by subject and turn a migration into an archaeology exercise. Keep depth shallow; two levels is nearly always enough.
One structural habit pays for itself repeatedly: keep a single canonical copy of each image and reference it from wherever it is needed, instead of uploading a fresh copy per page. Multiple near-identical files with different names is the mess behind most of the confusion about whether reusing the same photo across pages causes a problem. The question is far easier to reason about when there is genuinely one file.
Retrofitting a site that never had one
The instinct is to rename everything. Resist it.
A published image URL is an address that other things point at: internal links, external links, image-search results, cached copies, social previews, and your own sitemap. Renaming discards that unless every old URL redirects to its new one, and a bulk rename across thousands of files produces a redirect map nobody maintains.
The proportionate sequence:
- Apply the convention to everything new, starting today. This is the entire long-term fix. Everything below is cleanup.
- Inventory what exists. Crawl the site and list every image URL with the page it appears on. A full-site image inventory is an afternoon's work, and its main output is knowing how bad the problem actually is rather than guessing.
- Rank the offenders by page value. A camera-code filename on your highest-traffic service page is worth fixing. The same filename on a 2019 blog post nobody reads is not.
- Rename the top slice, with redirects. Old URL to new URL, permanently. Update the references in your content at the same time so you are not relying on the redirect forever.
- Regenerate the sitemap and wait. Image recrawl is slower than page recrawl, and this change is not urgent enough to chase.
If a rename is happening as part of a larger site change, fold it into that project rather than running it separately. The redirect discipline, the sitemap regeneration and the recrawl waiting period are the same work either way, and doing them once is much safer than doing them twice. The rules for keeping image rankings through a redesign or migration apply directly.
Writing it down
The document itself should be short enough that someone reads all of it. In practice that is about a page:
- the token pattern, with three real examples taken from your own site
- the rules table
- the validation expression, copy-pasteable
- where the check runs
- the exception process, which should be one named person
Anything longer gets skimmed. Anything that lives only as prose gets ignored within a quarter, which is why the validation rule is the load-bearing part and the document is merely the explanation of it.
What this is and is not worth
A naming convention will not move a page up the results on its own. Filenames are a modest, well-documented, genuinely-read signal, and the honest framing is that they are one of several things that together make an image findable, alongside alt text, surrounding copy, page relevance and whether the file can be crawled at all. The twelve-item pre-publish checklist puts the filename in that context.
What a convention does deliver is compounding. Every image added from now on is descriptive without anyone deciding to make it so, the library stays auditable, migrations stop being frightening, and the failure mode of a rushed upload becomes a rejected file rather than a permanent camera code on a page that matters.
At volume, that shifts from a nice-to-have to the only workable approach. When a batch of images is produced and shipped in one pass, the naming decision has to be made once by a rule rather than a hundred times by a person. That is the whole argument for encoding the convention somewhere a machine can read it. And if you would rather the filenames, alt text and metadata were simply correct at the moment each image is created, that is what SEOpix writes automatically on every plan, including the free one.
Frequently asked questions
What is the best SEO image naming convention?+
A short, hyphen-separated, all-lowercase string of two to five descriptive tokens ordered from most specific to most general, with no stop words, no dates and no camera codes. As of August 2026 Google's own guidance asks only for descriptive filenames, so everything beyond that is an internal consistency decision rather than a ranking rule. The value of a convention is that it makes descriptiveness automatic instead of leaving it to whoever happens to upload the file.
Should image filenames use hyphens or underscores?+
Hyphens. Google has stated for years that hyphens are treated as word separators in URLs while underscores join words together, so red_brick_wall can be read as a single token where red-brick-wall is read as three. The difference is small, but it costs nothing to get right, and mixed usage across one site is the actual problem worth eliminating.
Should the city or location go in the image filename?+
Include it when the image genuinely depicts or belongs to that location, and leave it out when it does not. A location token on a photograph taken somewhere else is the same category of mistake as keyword-stuffed alt text. Where location matters for local visibility, GPS coordinates in the file metadata carry the claim more precisely than a filename token ever will.
How long should an image filename be?+
Long enough to be unambiguous and short enough to read at a glance, which in practice means roughly three to six words or under about sixty characters. There is no documented length limit that affects ranking. The practical limits are readability in a file list, breakage in clients that wrap long URLs, and the fact that nobody maintains a convention that is tedious to type.
Do I need to rename images that are already published?+
Usually not. A published image URL accumulates links, image-search history and cached references, and renaming discards that unless you redirect the old URL to the new one. Apply the convention to everything new, rename only where the current filename is actively useless such as IMG_4021 on a page that matters, and always redirect when you do.
Should filenames include image dimensions or version numbers?+
Dimensions no, versions yes when the file can change. Dimensions go stale the moment a responsive pipeline generates its own sizes, and they describe the file rather than the subject. A short version suffix solves a real problem instead, because long cache lifetimes mean an image overwritten in place keeps serving the old bytes until the URL itself changes.
How do I enforce an image naming convention across a team?+
Put it in a lint rule or an upload validation step rather than a document. A regular expression that rejects uppercase, spaces, underscores and camera-code patterns catches nearly every violation at the moment it happens, which is the only moment anyone is willing to fix it. A convention that lives only in a wiki page degrades within a quarter.
Does the folder path matter as well as the filename?+
It is a weaker signal than the filename and mostly matters for human navigation and crawl clarity. A structure that groups images by section or content type is easier to audit, easier to migrate and easier to write sitemap rules against. Avoid deep paths built from dates, since almost nobody looks for an image by the month it was uploaded.
Let SEOpix handle the metadata
Filenames, alt text, EXIF fields and GPS coordinates written automatically as each image is generated. Start with 10 free images a month — no credit card required.
