Output paths & naming

imgsqz gives you four ways to decide where output lands. Pick based on whether you’re processing one file or many.

Default: timestamped, next to the source

With no naming flags, the output goes beside the input with a _<timestamp>.<ext> suffix:

imgsqz photo.png
# photo.png → photo_20260611_132517.jpg

The timestamp is YYYYMMDD_HHMMSS captured when the run starts. It guarantees a fresh name every run and means your source is never overwritten.

--no-timestamp: clean names

Drop the suffix to get name.<ext> next to the source:

imgsqz photo.png --no-timestamp
# photo.png → photo.jpg

Caution

With --no-timestamp, re-running the same command overwrites the previous output (e.g. a second run rewrites photo.jpg). It still won’t overwrite the input unless the input and output paths are identical — and in that case imgsqz refuses unless you add --replace.

-o, --output <path>: an exact destination

Name the output file precisely. The extension you give is just a name — the actual encoding is set by -f:

imgsqz photo.jpg -o build/thumb.webp -f webp -q 70

imgsqz creates missing directories in the path automatically, so this works even if build/ doesn’t exist yet:

imgsqz photo.jpg -o dist/img/hero.avif -f avif -q 50

Note

--output accepts a single input only. With multiple inputs you’ll get an error — use a shell loop to set per-file paths in a batch.

--replace: overwrite the source in place

Write the result back over the original file:

imgsqz photo.jpg --replace -q 80

This is the one case where the input is the output. It’s done atomically — imgsqz writes photo.jpg.imgsqz.tmp first, then renames it over photo.jpg — so an interrupted run can’t corrupt your file. See Replacing files in place for the full story.

How the output extension is chosen

The output extension follows the format, not the input:

Command	Output name
imgsqz a.png	a_<ts>.jpg (default format)
imgsqz a.png -f webp	a_<ts>.webp
imgsqz a.png -f webp --no-timestamp	a.webp
imgsqz a.png -o out/b.avif -f avif	out/b.avif
imgsqz a.png -f png --replace	a.png (in place)

Tip

jpeg normalizes to jpg, so the extension is always .jpg for JPEG output — even if you typed -f jpeg.

The “refuse to clobber” guard

If your flags would make the output path equal the input path and you did not pass --replace, imgsqz stops with:

Refusing to overwrite the input file. Use --replace if that's what you want,
or specify -o/--output.

This is a safety net — for example, imgsqz photo.jpg --no-timestamp (which would compute photo.jpg) is blocked unless you add --replace.

---

Next: Metadata & orientation.