Recursive WebP Conversion: How to Avoid Surprise Output

Recursive image conversion is powerful because it can process a whole folder tree at once. It is also risky because folder trees often contain more than approved source images. A command that walks every nested folder may find drafts, thumbnails, old exports, social images, already optimized files, and assets that were never meant for the website.

The safe way to use recursive WebP conversion is to make the folder structure explicit, preview the input set, and keep generated outputs separate. Advice such as "run it on your assets folder" hides too much risk in a real production tree. A recursive conversion plan should name the input root, the output root, the output path behavior, the collision check, and the review evidence you will keep.

Understand the Folder Before Running the Command#

Start by looking at the directory tree. You are checking for intent, not just file count.

site-assets/
  originals/
    blog/
    products/
    team/
  drafts/
  optimized/
  archive/

In this example, originals/ may be a good input path. site-assets/ includes drafts, previous outputs, and archive material, so it is the wrong root for this job.

Recursive conversion should begin from the narrowest folder that contains approved source images.

Run a Dry Run First#

A dry run gives you a preview before output files are created:

getwebp ./site-assets/originals --recursive --dry-run

If the preview count is unexpected, stop. Inspect the folder before converting. The dry run may reveal nested directories that were forgotten or file types that should be excluded from the current job.

This step is especially useful when the folder was prepared by another team member or exported from a CMS.

Write Output to a Separate Root#

Do not write generated WebP files into the same nested tree unless the project has a strong reason. A separate output root keeps the result readable:

getwebp ./site-assets/originals \
  --recursive \
  -o ./site-assets/webp-output \
  --quality 82

The GetWebP CLI conversion workflow writes each generated file into the selected output directory by output basename. In other words, -o ./site-assets/webp-output does not guarantee a mirrored copy of the nested source tree. These two files would target the same output filename:

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

When multiple inputs map to the same output filename, GetWebP warns that only the last processed file will survive. Treat that warning as a release blocker, not as a harmless log line. If your source tree has repeated basenames, split the job by subfolder, choose separate output directories, or use a workflow that preserves the relative tree for that use case.

You can pre-check repeated output names before converting:

find ./site-assets/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

No output from that command means it did not find duplicate target basenames. If it prints filenames, handle those folders separately before running the recursive conversion.

Avoid Reprocessing Generated Files#

Recursive jobs can accidentally process their own output if the output folder sits inside the input path. That can create duplicate files, nested output folders, or re-encoded images that should not have been touched. If you omit --output, generated files are written next to their source images, so the next broad recursive run may see those generated files too.

Keep output outside the input path:

input:  ./assets/originals
output: ./assets-generated/webp

Or at least make sure the output folder is excluded by the tool or workflow. The important rule is that generated files should not become source files by accident.

Use skip-existing for Repeat Runs#

When repeating a conversion, --skip-existing can reduce accidental overwrites:

getwebp ./site-assets/originals \
  --recursive \
  -o ./site-assets/webp-output \
  --quality 82 \
  --skip-existing

This is useful when new images are added to a folder over time. Still, do not treat it as a full review substitute. --skip-existing skips an image only when the computed output path already exists; it does not prove that the existing output was created from the current source file, current quality setting, or current release branch. If quality settings change, skipping existing files may leave a mixed output folder. Record why the repeat run is being used.

Check Special Folders#

Recursive source trees often include folders with different rules:

• logos/ may contain SVG files that should stay SVG
• screenshots/ may need higher quality or PNG fallback
• social/ may target platforms outside the website
• archive/ may contain old files not used anymore
• optimized/ may already contain generated files

If these folders need different settings, process them separately. One recursive command should not flatten different quality requirements into one setting.

Keep a Machine-Readable Report#

For production runs, keep the structured report rather than relying on terminal scrollback:

mkdir -p ./reports

getwebp ./site-assets/originals \
  --recursive \
  -o ./site-assets/webp-output \
  --quality 82 \
  --json > ./reports/recursive-webp.ndjson

The JSON output is newline-delimited. The convert.completed event contains successCount, failedCount, and a results array with file, outputPath, status, size fields, and quality information. Check it before moving files into a website build:

jq 'select(.type == "convert.completed") | .data.failedCount' ./reports/recursive-webp.ndjson

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

jq 'select(.type == "convert.truncated")' ./reports/recursive-webp.ndjson

A recursive run with hidden failures, truncated reporting, or unexpected output paths should not be published until the folder plan is fixed.

Review a Sample From Each Subfolder#

After conversion, do not review only the top-level files. Pick at least one output from each important subfolder. This catches problems where a nested folder contains screenshots, transparent assets, or product images that need different treatment.

GetWebP's CLI command reference documents --recursive, --output, --dry-run, and --skip-existing, and the JSON output guide shows the event structure used above. Google's WebP documentation explains the format, and MDN's image file type guide helps compare formats when a subfolder should not become WebP.

Use a Pre-Publish Checklist#

Before the converted tree is uploaded or committed, check:

• the output folder contains only generated files
• no drafts or archive images were processed
• source images are still untouched
• duplicate target basenames were checked before using one shared output directory
• convert.completed reports zero failures
• results[].outputPath points to the expected output root
• repeated runs used the intended overwrite or skip behavior
• one sample from each subfolder passed visual review
• links or manifests point to the new paths

This checklist catches workflow errors that visual review alone will miss.

Recursive conversion is useful when the input tree is clean. Make the input narrow, preview with dry run, keep outputs separate, avoid reprocessing generated files, and review subfolders individually. That turns recursion from a risky shortcut into a controlled workflow.