Image Naming Rules for Clean WebP Migrations

Image migration problems are often blamed on formats when the real issue is naming. A team converts hundreds of files to WebP, uploads them to a CMS or CDN, and later cannot tell which output came from which source, which size is used by which template, or which file should be removed after a rollback.

Good filenames do not need to be clever. They need to be consistent, readable, and stable enough that humans and tools can understand the relationship between source files and optimized outputs.

A naming guide is weak when it stops at "use lowercase and hyphens." For a real migration, the filename rule has to answer harder questions: whether two source paths produce the same WebP name, which public URL maps to which generated file, whether CMS imports preserve case, and what evidence the team will keep when a conversion job partially succeeds.

Preserve the Source Name When Possible#

The simplest migration rule is to keep the base name and change only the extension:

team-photo.jpg
team-photo.webp

This makes source-to-output mapping obvious. It also helps when reviewing diffs, CDN objects, CMS media records, or generated manifests.

Avoid renaming team-photo.jpg to compressed-final-new.webp or image-1.webp. Those names may be understandable for a few minutes during export, but they become maintenance debt as soon as the project grows.

This rule is only safe when the base name is unique inside the output scope. If two folders both contain hero.jpg, preserving the base name may make the migration less clear, not more clear.

Add Widths for Responsive Variants#

When you generate multiple sizes, include the width in the filename:

hero-640.webp
hero-960.webp
hero-1280.webp
hero-1600.webp

The width should describe the actual pixel width of the file. Do not use a label such as large unless the project also records what large means. Numeric widths make srcset markup easier to inspect and help catch mismatches.

If the source file is hero.jpg, the generated filenames should still keep the base name:

hero-640.jpg
hero-640.webp

This keeps fallback pairs aligned.

Avoid Encoding Quality in Public Names#

During testing, names such as product-q78.webp are useful. In production, quality values in public filenames often create confusion. If you later re-encode the file at a different setting, the filename becomes inaccurate unless every reference changes.

A better pattern is to keep quality settings in a build manifest, processing note, or versioned conversion script. Public filenames should usually represent identity and dimensions, not every internal processing parameter.

An exception is a temporary QA folder, where quality labels help reviewers compare candidates:

qa/product-bag-q76.webp
qa/product-bag-q84.webp

Keep those candidates out of the final upload folder.

Use Lowercase and Simple Separators#

Use lowercase filenames with hyphens:

pricing-dashboard-960.webp

Avoid spaces, mixed case, punctuation, and characters that need escaping in URLs. This reduces friction across operating systems, command-line tools, CDNs, CMS imports, and HTML templates.

The rule is not about style preference. It is about reducing small sources of failure in a workflow that may involve designers, developers, build tools, storage buckets, and editors.

Treat case changes as migrations, not cosmetic edits. A CMS or storage bucket can behave differently from a local laptop, and links such as /images/Hero.webp and /images/hero.webp should not be assumed to resolve to the same object.

Do Not Reuse Names for Different Images#

Replacing a file with a visually different image under the same URL can create cache confusion. Browsers, CDNs, and CMS layers may continue serving an older file until cache entries expire or are purged.

If the image identity changes, change the filename:

homepage-hero-spring-1280.webp
homepage-hero-summer-1280.webp

If only compression settings change and the visual content is the same, you may keep the name if your deployment process handles cache invalidation. Otherwise, versioned filenames can make rollout safer.

Keep Originals and Outputs Separate#

Filename rules work best with folder rules:

images/
  originals/
    homepage-hero.jpg
  optimized/
    homepage-hero-1280.webp

Do not mix drafts, sources, QA candidates, and approved outputs in one folder. A clean folder structure makes it harder to upload the wrong file and easier to delete generated outputs when settings change.

Google's WebP documentation covers the format side of the migration, while MDN's srcset documentation helps explain why width-specific filenames are useful for responsive images.

Check Output Basenames Before Conversion#

If you convert a nested folder into one output directory, check duplicate target names before writing files. The GetWebP CLI supports recursive conversion, but getwebp ./images/originals --output ./images/optimized writes by output basename in the selected output directory; it does not mirror the nested source tree for the standard conversion command.

That means these two sources want the same output path:

images/originals/products/hero.jpg
images/originals/team/hero.png

Both can become:

images/optimized/hero.webp

GetWebP detects this kind of conflict and warns that only the last processed output will survive. The better workflow is to catch it before conversion and either rename one source, split the output directories, or add width/context tokens such as product-hero-1280.webp and team-hero-1280.webp.

One simple precheck is to normalize each candidate to the WebP basename and list duplicates:

find ./images/originals -type f \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.bmp' -o -iname '*.webp' -o -iname '*.heic' -o -iname '*.heif' -o -iname '*.avif' \) -print |
  sed -E 's#^.*/##; s#\.[^.]+$#.webp#' |
  sort | uniq -d

Any output from that command deserves a naming decision before the migration writes files.

Record the Actual Source-to-Output Map#

Run a dry run first so the team can review the input set without creating files:

getwebp ./images/originals --recursive --output ./images/optimized --dry-run

Then keep an NDJSON report from the real conversion:

getwebp ./images/originals \
  --recursive \
  --output ./images/optimized \
  --json > ./reports/webp-naming.ndjson

The report can be reduced to a review table:

jq -r 'select(.type=="convert.completed") | .data.results[] | [.status,.file,(.outputPath // ""),(.error // "")] | @tsv' ./reports/webp-naming.ndjson

Also check for free-plan truncation before treating the migration as complete:

jq -r 'select(.type=="convert.truncated") | .data' ./reports/webp-naming.ndjson

The CLI command options are documented in the GetWebP CLI command reference, and the report structure is covered in the JSON output guide.

Add a Manifest for Larger Projects#

For a small website, consistent filenames may be enough. For a large migration, create a manifest that maps sources to outputs:

{
  "source": "homepage-hero.jpg",
  "outputs": ["homepage-hero-640.webp", "homepage-hero-1280.webp"],
  "reviewed": true
}

The manifest helps with audit, rollback, and future regeneration. It also prevents the team from guessing which files are safe to delete.

If you use GetWebP's --manifest option, remember that the manifest records successful conversions and fingerprints. It is not a substitute for the NDJSON conversion report when you need to review failures, skipped files, or truncation events.

Define Deletion Rules#

Before cleanup, decide which files are generated and which files are source material. Generated WebP files can usually be recreated if the originals, settings, and manifest are available. Source files should not be deleted just because the migration succeeded.

This rule matters when storage costs or media libraries become messy. Delete with a record, not from memory.

Clean naming will not make a bad conversion setting good. It will make the migration understandable. That is what teams need when image optimization moves from a one-time experiment to a repeatable publishing workflow.