Core concepts

Once you understand these five concepts, every flag in imgsqz makes sense.

1. The anatomy of a command

imgsqz <input...> [options]

• <input...> — one or more image paths (globs are expanded by your shell). This is the only required argument.
• [options] — flags that control format, quality, size, naming and safety.

Everything else is a variation on this shape.

2. Sensible defaults

Run imgsqz with just an input and you get a deliberate set of defaults:

Default	Value	Why
Format	jpg	Universally supported, great with mozjpeg
Quality	80	A strong size/quality sweet spot
Output	<name>_<timestamp>.jpg next to source	Never overwrites your original
Metadata	stripped	Smaller files; privacy by default
Orientation	auto-corrected	Phone photos come out upright
Resize	none	Keeps original dimensions

So imgsqz photo.png means “make a stripped, upright, quality-80 JPG copy and don’t touch my original.”

3. Output naming & the timestamp

By default the output filename is derived from the input:

photo.png  →  photo_20260611_132517.jpg
                    └─ YYYYMMDD_HHMMSS at the moment you ran it

The timestamp guarantees runs don’t collide and your source is safe. You can change this behavior:

• --no-timestamp drops the suffix → photo.jpg
• -o, --output <path> sets an exact path (single input only)
• --replace overwrites the source in place (see safety below)

Caution

--output works with a single input. Combining it with multiple inputs is an error — there’s no one path that could hold many results. Use --no-timestamp or --replace for batches instead.

4. Safety: your source is never clobbered by accident

imgsqz goes out of its way not to destroy originals:

• The default timestamped name can’t collide with the source.
• If a computed output path would equal the input and you didn’t pass --replace, imgsqz refuses and tells you to use --replace or -o.
• --replace itself is atomic: it writes to a temporary file (name.imgsqz.tmp) and then renames it over the original. An interrupted run leaves your source intact.

5. The pipeline order

For each input, imgsqz builds a sharp pipeline in a fixed order:

read ─▶ auto-rotate (EXIF) ─▶ resize? ─▶ grayscale? ─▶ keep metadata? ─▶ encode ─▶ write

Knowing this order explains the interactions:

• Rotate happens first, so --width/--height apply to the upright image.
• Resize honors orientation, so “width” always means visual width.
• Encoding is last, so format-specific flags (--lossless, --quality) apply to the final pixels.

Note

Want the gritty per-format encoder details (mozjpeg, PNG palette, AVIF effort, TIFF LZW)? See Format behavior.

---

That’s the whole mental model. Next: Compressing images.