OPTIPNG(1)

📦
version 7.9.1 · 4 versions
, in alpine 3.24, arch rolling, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 OPTIPNG(1) — OptiPNG Manual 🦋

okay bestie, welcome to the OptiPNG manual, and no cap this is the glow-up your PNGs have been begging for 💅

✨ NAME ✨

optipng — optimize Portable Network Graphics (PNG) files

like... it makes your PNGs skinnier. that's the whole job. she's an icon, she's a legend, and she's about to shrink ur files 🌸

🌈 SYNOPSIS 🌈

optipng [<options...>] [--] <files...>

💖 DESCRIPTION 💖

so the OptiPNG program shall attempt to optimize PNG files, i.e. to reduce their size to a minimum, without losing semantic information. no quality lost, only bytes lost ✨

on top of that, this program shall also perform a whole suite of auxiliary functions like integrity checks, metadata recovery and pixmap-to-PNG conversion. she does it all fr fr 👑

🫶 heads up tho: the optimization attempts are not guaranteed to succeed.

valid PNG files that cannot be optimized by this program are normally left intact — their size will not grow. the user may request to override this default behavior. (that's the -force option, we'll get there 💜)

🎀 FILES 🎀

the input files are raster image files encoded either in PNG format (the native format), or in an external format. the currently supported external formats are GIF, BMP, PNM and TIFF.

OptiPNG processes each image file given in the command line as follows:

  • if the image is in PNG format:

it attempts to optimize the given file in-place. if optimization is successful, or if the option -force is enabled, the original file will be replaced by its optimized version. in any case, the original file will be backed up if the option -keep is enabled. 🫶

  • if the image is in an external format:

it creates an optimized PNG version of the given file. the output file name will be constructed using the original file name and the .png extension. cute, right? 🦋

aside from the rules stated above, any existing file is not overwritten, unless the option -clobber is enabled. (respect the existing files bestie, that's the default 🌸)

💅 OPTIONS 💅

🌟 General options 🌟

  • -?, -h, -help — show a complete summary of options. the "help me help you" trio 💖
  • -backup, -keep — keep a backup of the modified files. always protect the original, periodt.
  • -clobber — overwrite the existing output and backup files. under this option, if the option -backup is not enabled, the old backups of the overwritten files will be deleted. 💀 so yeah, be careful.
  • -dir directory — write the output files to directory.
  • -fix — enable error recovery. this option has no effect on valid input files. the program will spend a reasonable amount of effort to recover as much data as possible, without increasing the output file size, but the success cannot be generally guaranteed. the program may even increase the file size, e.g., by reconstructing missing critical data. under this option, integrity shall take precedence over file size. when this option is not used, the invalid input files are left unprocessed.
  • -force — enforce writing of a new output file. this option overrides the program's decision not to write such file, e.g. when the PNG input is digitally signed (using dSIG), or when the PNG output becomes larger than the PNG input. main character energy: she writes the file anyway 😤
  • -out file — write output file to file. the command line must contain exactly one input file.
  • -preserve — preserve file attributes (time stamps, file access rights, etc.) where applicable. 🎀
  • -quiet, -silent — run in quiet mode. shhh 🤫
  • -simulate — run in simulation mode: perform the trials, but do not create output files. all vibes, no files ✨
  • -v — enable the options -verbose and -version.
  • -verbose — run in verbose mode. tell me EVERYTHING 🗣️
  • -version — show the copyright, version and build info.
  • -- — stop option switch parsing. the "okay that's enough options" barrier 🚧

🧚 PNG encoding and optimization options 🧚

  • -o level — select the optimization level.
    • the optimization level 0 enables a set of optimization operations that require minimal effort. there will be no changes to image attributes like bit depth or color type, and no recompression of existing IDAT datastreams.
    • the optimization level 1 enables a single IDAT compression trial. the trial chosen is what OptiPNG thinks it might be the most effective.
    • the optimization levels 2 and higher enable multiple IDAT compression trials; the higher the level, the more trials.
the behavior and the default value of this option may change across different program versions. use the option -h to see the details pertaining to your specific version. iykyk 💜
  • -f filters — select the PNG delta filters. the filters argument is specified as a rangeset (e.g. -f0-5), and the default filters value depends on the optimization level set by the option -o. the filter values 0, 1, 2, 3 and 4 indicate static filtering, and correspond to the standard PNG filter codes (None, Left, Up, Average and Paeth, respectively). the filter value 5 indicates adaptive filtering, whose effect is defined by the libpng(3) library used by OptiPNG.
  • -full — produce a full report on IDAT. this option might slow down the trials. thorough but she takes her time 🐢
  • -i type — select the interlace type (0-1). if the interlace type 0 is selected, the output image shall be non-interlaced (i.e. progressive-scanned). if the interlace type 1 is selected, the output image shall be interlaced using the Adam7 method. by default, the output shall have the same interlace type as the input.
  • -nb — do not apply bit depth reduction.
  • -nc — do not apply color type reduction.
  • -np — do not apply palette reduction.
  • -nx — do not apply any lossless image reduction: enable the options -nb, -nc and -np.
  • -nz — do not recode IDAT datastreams. the IDAT optimization operations that do not require recoding (e.g. IDAT chunk concatenation) are still performed. this option has effect on PNG input files only.
  • -zc levels — select the zlib compression levels used in IDAT compression. the levels argument is specified as a rangeset (e.g. -zc6-9), and the default levels value depends on the optimization level set by the option -o. the effect of this option is defined by the zlib(3) library used by OptiPNG.
  • -zm levels — select the zlib memory levels used in IDAT compression. the levels argument is specified as a rangeset (e.g. -zm8-9), and the default levels value depends on the optimization level set by the option -o. the effect of this option is defined by the zlib(3) library used by OptiPNG.
  • -zs strategies — select the zlib compression strategies used in IDAT compression. the strategies argument is specified as a rangeset (e.g. -zs0-3), and the default strategies value depends on the optimization level set by the option -o. the effect of this option is defined by the zlib(3) library used by OptiPNG.
  • -zw size — select the zlib window size (32k,16k,8k,4k,2k,1k,512,256) used in IDAT compression. the size argument can be specified either in bytes (e.g. 16384) or kilobytes (e.g. 16k). the default size value is set to the lowest window size that yields an IDAT output as big as if yielded by the value 32768. the effect of this option is defined by the zlib(3) library used by OptiPNG.

🌸 Editing options 🌸

  • -snip — cut one image out of multi-image, animation or video files. depending on the input format, this may be either the first or the most relevant (e.g. the largest) image. ✂️
  • -strip objects — strip metadata objects from a PNG file. PNG metadata is the information stored in any ancillary chunk except tRNS. (tRNS represents the alpha channel, which, even if ignored in rendering, is still a proper image channel in the RGBA color space.) the only option currently supported is -strip all.

🍓 Notes 🍓

options may come in any order (except for --), before, after, or alternating with file names. option names are case-insensitive and may be abbreviated to their shortest unique prefix. slay, flexible queen 💅

some options may have arguments that follow the option name, separated by whitespace or the equal sign (=). if the option argument is a number or a rangeset, the separator may be omitted. for example:

optipng -out newfile.png  <=>  optipng -out=newfile.png
optipng -o3  <=>  optipng -o 3  <=>  optipng -o=3
optipng -f0,3-5  <=>  optipng -f 0,3-5  <=>  optipng -f=0,3-5

rangeset arguments are cumulative. for example:

optipng -f0 -f3-5  <=>  optipng -f0,3-5
optipng -zs0 -zs1 -zs2,3  <=>  optipng -zs0-3

👑 EXTENDED DESCRIPTION 👑

the PNG optimization algorithm consists of the following steps:

  1. reduce the bit depth, the color type and the color palette of the image. this step may reduce the size of the uncompressed image, which, indirectly, may reduce the size of the compressed image (i.e. the size of the output PNG file).
  2. run a suite of compression methods and strategies and select the compression parameters that yield the smallest output file.
  3. store all IDAT contents into a single chunk, eliminating the overhead incurred by repeated IDAT headers and CRCs.
  4. set the zlib window size inside IDAT to a minimum that does not affect the compression ratio, reducing the memory requirements of PNG decoders.

not all of the above steps need to be executed. the behavior depends on the actual input files and user options.

step 1 may be customized via the no-reduce options -nb, -nc, -np and -nx. step 2 may be customized via the -o option, and may be fine-tuned via the options -zc, -zm, -zs and -zw. step 3 is always executed. step 4 is executed only if a new IDAT is being created, and may be fine-tuned via the option -zw.

extremely exhaustive searches are not generally expected to yield significant improvements in compression ratio, and are recommended to advanced users only. so like... don't come for me if -o7 takes forever, bestie 😭

⭐ EXAMPLES ⭐

optipng file.png      # default speed
optipng -o5 file.png  # slow
optipng -o7 file.png  # very slow

pick ur fighter: chill, patient, or "i have time today" 🐌✨

💀 BUGS 💀

lossless image reductions are not completely implemented. (this does not affect the integrity of the output files.) here are the missing pieces:

  • the color palette reductions are implemented only partially.
  • the bit depth reductions below 8, for grayscale images, are not implemented yet.

encoding of images whose total IDAT size exceeds 2GB is not currently supported.

TIFF support is limited to uncompressed, PNG-compatible (grayscale, RGB and RGBA) images.

metadata is not imported from the external image formats.

there is no support for pipes, streams, extended file attributes or access control lists.

ngl, she's still growing into her full power 🌱 but the integrity stays intact, periodt.

🔥 SEE ALSO 🔥

png(5), libpng(3), zlib(3), pngcrush(1), pngrewrite(1).

...and that's part 1, bestie — more coming, don't go anywhere 💜

🌈 STANDARDS

Okay bestie, vibe check on compatibility real quick: the files OptiPNG spits out are compliant with the most recent PNG standard (they call it "PNG Second Edition") ✨ and also with the most recent PNG draft standard (aka "PNG Third Edition") 💅. Like, both. Simultaneously. Iconic behaviour, honestly.

💖 AUTHORS

Screaming, crying, throwing up — OptiPNG is written and maintained by Cosmin Truta 👑. Legend behaviour. No notes.

And this manual page you're reading rn? It was originally written by Nelson A. de Oliveira for the Debian Project 🫶, then later updated by Cosmin Truta, and it is now part of the OptiPNG distribution. A whole collaborative storyline, fr fr. 🦋

💌 that's the whole page, bestie — go forth and optimise your PNGs, you absolute main character 🌸

optipng 7.9.1 · 2025-05-20 · OPTIPNG(1) 🎀✨ bye ily 🫶

📦 where this page comes from