How to Convert a Folder to WebP Without Breaking Links

Converting a folder of images to WebP is easy. Shipping those images without breaking pages is the harder part. Links, CMS records, responsive variants, CDN caches, and fallback files all need to agree. A folder conversion should be treated as a migration, not just an export.

The safest approach is to keep originals untouched, write WebP outputs to a separate location, create a mapping between old and new files, and update references only after review. Advice about "just convert the folder and replace extensions" is too thin for a real migration because the filesystem path, generated output path, public URL, CDN cache key, and fallback reference may all be different.

Make a Clean Source Copy#

Start with a folder that contains only the images you intend to process. Do not point a converter at a mixed downloads folder full of drafts, source design files, and unused exports.

Use a structure like this:

web-images/
  originals/
  webp-output/
  qa-notes/

The originals folder should not be modified. If the migration fails, you still have the source files and can regenerate outputs with different settings.

Convert Into a Separate Output Folder#

Preview the candidate input set first:

getwebp ./web-images/originals --dry-run

Then write WebP files into a separate folder:

getwebp ./web-images/originals -o ./web-images/webp-output --quality 82

This keeps the conversion step reversible. It also prevents the generated files from being mistaken for the original inputs.

If your source folder has nested directories, make recursion explicit:

getwebp ./web-images/originals --recursive --dry-run

getwebp ./web-images/originals \
  --recursive \
  -o ./web-images/webp-output \
  --quality 82

Do not assume that a recursive conversion with one shared --output directory mirrors the source tree. In the GetWebP CLI conversion workflow, generated files are written to the selected output directory by basename. That means these inputs can target the same output file:

originals/products/chair.jpg -> webp-output/chair.webp
originals/team/chair.png     -> webp-output/chair.webp

If your migration depends on a mirrored public path, split the conversion by subfolder, use separate output directories, or build your own copy step after conversion. Treat any filename conflict warning as a blocker before updating links.

Run this on a small sample first if the folder is large. Ten representative files can reveal naming, quality, path, and collision issues before the migration touches the entire image set.

Build a Reference Map#

Before editing HTML, templates, or CMS records, create a map from source file to generated output and then from generated output to public URL:

source file                  generated file              public URL
originals/products/chair.jpg webp-output/chair.webp      /images/products/chair.webp
originals/team/sarah.png     webp-output/sarah.webp      /images/team/sarah.webp

For responsive images, include every variant. For fallback markup, include both the new WebP and the existing JPEG or PNG. This map is the migration record. It helps reviewers understand what changed and makes rollback possible.

Avoid relying on memory or filename similarity when many files are involved.

For a real conversion, capture structured output:

getwebp ./web-images/originals \
  --recursive \
  -o ./web-images/webp-output \
  --quality 82 \
  --json > ./web-images/qa-notes/conversion.ndjson

Then extract the generated paths:

jq -r '
  select(.type == "convert.completed")
  | .data.results[]
  | [.status, .file, (.outputPath // ""), (.error // "")]
  | @tsv
' ./web-images/qa-notes/conversion.ndjson

jq 'select(.type == "convert.truncated")' ./web-images/qa-notes/conversion.ndjson

The GetWebP CLI command reference documents --output, --recursive, and --dry-run, and the JSON output guide explains convert.completed, convert.truncated, and results[].outputPath.

If your build needs fingerprinted filenames, you can also write a manifest:

getwebp ./web-images/originals \
  --recursive \
  -o ./web-images/webp-output \
  --quality 82 \
  --manifest ./web-images/qa-notes/manifest.json

Use the manifest as a successful-output inventory, not as proof that every intended file converted. Failed and truncated runs still need the structured conversion report and exit status.

Update References in the Right Place#

Where you update links depends on the site:

• static HTML files
• component templates
• Markdown or MDX content
• CMS media records
• database fields
• build-time image manifests
• CDN rewrite rules

Do not update only the visible page content if the site also uses generated cards, open graph images, search previews, or RSS feeds. A broken image in a feed or share card is still part of the migration.

Do not update references by replacing .jpg or .png with .webp globally unless your map proves the new public URL exists. A safe link migration follows the generated outputPath, the deploy location, and the site's URL routing rules.

Use Picture When a Fallback Is Needed#

If the site needs a fallback format, use the picture element:

<picture>
  <source srcset="/images/products/chair.webp" type="image/webp" />
  <img src="/images/products/chair.jpg" alt="Oak dining chair with woven seat" />
</picture>

The fallback img must remain valid. Do not delete the JPEG or PNG until you are sure no page, client, CMS preview, or integration needs it.

MDN's picture documentation explains the markup model, and Google's WebP documentation covers the format itself.

Test the Real Pages#

After updating references, test the actual pages that use the images. Check:

• homepage and landing pages
• product or portfolio pages
• blog posts
• search result cards
• related-content modules
• mobile layouts
• open graph previews if relevant

Use the browser network panel to confirm that the expected WebP files load and that old references do not return 404s. Also check that the fallback files still load where fallback markup is used. If an image appears only because the browser cache is warm, a private window or cache-disabled reload should expose that before users do.

Watch Caches and Case Sensitivity#

Broken links often come from small path differences: uppercase letters, spaces, missing folders, or stale CDN cache entries. A file that works on a local macOS machine may fail on a case-sensitive Linux server if the path does not match exactly.

Before launch, verify filenames and paths in the deployed environment. If the CDN cached an old image or old HTML, purge or version the relevant files.

Keep Rollback Simple#

Do not delete originals or fallback files immediately after launch. Keep the reference map and source folder until the migration has been stable through normal traffic and content updates.

A clean folder conversion is not measured only by how many files were compressed. It is measured by whether the site still renders correctly, editors can understand the new files, and the team can recover if a bad reference slips through.