resize
Resize by pixels, scale factor, longest edge, or physical size at a DPI.
Resize to new dimensions. Exactly one sizing mode is required; the rest are optional.
resize <inputs...> (--width W | --height H | --scale F | --longest PX | --mm WxH --dpi D) [--fit contain|cover|fill] [--to <size>] [--format …] [--dpi D] [--background #hex]Flags
| Flag | Meaning |
|---|---|
--width W / --height H |
pixel target for one or both axes (a positive integer). Counts as one sizing mode together. |
--scale F |
multiply both dimensions by a positive number, e.g. --scale 0.5 for half size. |
--longest PX |
scale so the longer edge is exactly PX pixels (a positive integer). |
--mm WxH |
physical size in millimetres, e.g. 35x45 for a passport photo. Requires --dpi. |
--fit contain|cover|fill |
how to fit the box for --width/--height/--mm. Default contain. Ignored by --scale/--longest, which have no box to fit. |
--to <size> |
also hit a byte target after resizing (same parser as compress’s --to). Without it, the resize re-encodes at a fixed quality of 90. |
--format keep|jpeg|png|webp |
output format. Default keep. |
--dpi D |
declare an output DPI, independent of pixel dimensions — a passport-photo tool needs both 35x45mm at 300 DPI (pixels) and a file that says 300 DPI. Legal on its own even without --mm. |
--background #hex |
flatten color for alpha composited onto a non-alpha format (jpeg). Default #ffffff. Accepts #rgb, #rrggbb, white, or black. |
Exactly one of --width/--height, --scale, --longest, or --mm must be given — zero or more
than one is a usage error. --mm without --dpi is also a usage error: there’s no way to convert
millimetres to pixels without a DPI.
Examples
Passport photo — 35×45mm at 300 DPI, filling the box exactly:
imagekbreducer resize photo.jpg --mm 35x45 --dpi 300 --fit fillHalf-size thumbnail, also capped at 30 KB:
imagekbreducer resize photo.jpg --scale 0.5 --to 30kb --format webpWhat can go wrong
| Exit | When |
|---|---|
| 2 | zero or more than one sizing mode given; --mm without --dpi; any flag value fails its own validation (--width/--height/--longest not a positive integer, --scale/--dpi not a positive number, --mm not WxH, --fit/--format not one of the allowed values, --background not a valid color) |
| 3 | an input doesn’t exist, or a glob matched nothing |
| 4 | the computed output already exists and isn’t the input |
| 10–13 | only reachable when --to is given — see Exit codes; without --to, the resize always succeeds at a fixed quality |
| 20–24 | engine-side failures — see Exit codes |
targetBytes in the --json envelope is null whenever --to was omitted —
resize only has a byte target when you ask for one.