oxipng(1)

📦
version 10.2.1 · 5 versions
, in arch rolling

💅 oxipng — okay bestie, let's talk about this ICONIC lossless PNG compression optimizer

So like, oxipng is literally that girl when it comes to making your PNGs smaller without losing any quality. Lossless compression optimizer, no cap. She's the main character of PNG optimization and honestly? Obsessed. 🎀

✨ SYNOPSIS ✨

oxipng [-o|--opt] [-r|--recursive] [--dir] [--out] [--stdout]
[-p|--preserve] [-d|--dry-run] [-s ] [--strip] [--keep] [-a|--alpha]
[-i|--interlace] [--scale16] [-v|--verbose]... [-q|--quiet] [-j|--json]
[-f|--filters] [--fast] [--zc] [--nb] [--nc] [--np] [--ng] [--nx] [--nz]
[--fix] [--force] [-z|--zopfli] [--zi] [--ziwi] [--brute-level]
[--brute-lines] [--timeout] [--max-raw-size] [-t|--threads]
[--sequential] [-h|--help] [-V|--version] <files>

🌸 DESCRIPTION 🌸

A lossless PNG compression optimizer. That's it. That's the vibe. She squeezes your PNGs down to their smallest possible size and never loses a single pixel doing it. 💖

🦋 OPTIONS 🦋

Okay so here's the whole menu, bestie. Read it, learn it, love it. 👑

  • -o, --opt <level> — [default: 2] — Pick your optimization level preset. Level 2 is literally the sweet spot: fast and good compression. Lower levels go zoom, higher levels squeeze harder but with increasingly diminishing returns (iykyk). Here's the whole lineup:
0   => --zc 5  -f 0,5         --fast
1   => --zc 10 -f 0,7         --fast
2   => --zc 11 -f 0,1,6,7     --fast
3   => --zc 11 -f 0,1,6,7,8,9 --fast --brute-level 1
--brute-lines 3
4   => --zc 12 -f 0,1,6,7,8,9 --fast --brute-level 1
--brute-lines 4
5   => --zc 12 -f 0,1,6,7,8,9        --brute-level 1
--brute-lines 8
6   => --zc 12 -f 0-9                --brute-level 5
--brute-lines 8
max => (stable alias for the maximum level)

If you manually set a compression option (like zc, f, etc.), it overrides whatever the preset says. Doesn't matter what order you write the args in — the manual one wins, periodt.

  • -r, --recursive — If you hand her directories, she goes full detective mode and traverses the whole tree, optimizing every PNG she finds (files ending in “.png” or “.apng”). Slay.
  • --dir <directory> — Write your output file(s) into <directory>. Don't worry if it doesn't exist yet — she'll create it. ⚠️ Heads up: this will not preserve the directory structure of your input files when you're using it with --recursive. So like, flat output energy.
  • --out <file> — Write the output file to <file>. Simple. Clean. Iconic.
  • --stdout — Write output to stdout. For the pipe girlies. 🫶
  • -p, --preserve — Preserve file permissions and timestamps if possible. Respectful queen.
  • -d, --dry-run — Do not write any files, only show compression results. A little preview moment, no commitment.
  • -s — Strip safely-removable chunks, same as --strip safe.
  • --strip <mode> — Strip metadata chunks, where <mode> is one of:
safe    =>  Strip all non-critical chunks, except for the
            following:
                cICP, iCCP, sRGB, pHYs, acTL, fcTL, fdAT
all     =>  Strip all non-critical chunks
<list>  =>  Strip chunks in the comma-separated list, e.g.
            'bKGD,cHRM'
🚨 CAUTION: all will convert APNGs to standard PNGs. So if you had animation dreams, they're gone.

Also please note that some chunks will necessarily be stripped when invalidated by the optimization:

  • bKGD, sBIT, hIST: Stripped if the color type or bit depth changes. If explicitly retained by --keep, reductions will be disabled.
  • caBX, iDOT: Stripped by default. If explicitly retained by --keep, optimization will be aborted.

The default when --strip is not passed is to keep all chunks that remain valid.

  • --keep <list> — Strip all metadata chunks except those in the comma-separated list. The special value display includes chunks that affect the image appearance, equivalent to --strip safe.

Example: --keep eXIf,display will strip chunks, keeping only eXIf and those that affect the image appearance. 💖

  • -a, --alpha — Do extra optimization on images with an alpha channel by altering the color values of fully transparent pixels. Generally recommended for better compression, but ⚠️ be careful: while this is “visually lossless”, it is technically a lossy transformation and may be unsuitable for some applications. Know your use case, bestie.
  • -i, --interlace <mode> — [default: off] — Set the PNG interlacing mode, where <mode> is one of:
off   =>  Remove interlacing from all images that are
          processed
on    =>  Apply Adam7 interlacing on all images that are
          processed
keep  =>  Keep the existing interlacing mode of each image

Heads up: interlacing can add 25-50% to the size of an optimized image. Only use it if you believe the benefits outweigh the costs for your use case. It's giving ✨ tradeoffs ✨.

  • --scale16 — Forcibly reduce images with 16 bits per channel to 8 bits per channel. This is a lossy operation but can provide significant savings when you have no need for higher depth. Reduction is performed by scaling the values such that, e.g. 0x00FF is reduced to 0x01 rather than 0x00.

Without this flag, 16-bit images will only be reduced in depth if it can be done losslessly.

  • -v, --verbose — Show per-file info. Use it multiple times for more detail. The more you ask, the more she tells you. 💅
  • -q, --quiet — Suppress all output messages. Shy mode.
  • -j, --json — Print results as JSON. For the programmatic besties.
  • -f, --filters <list> — Perform compression trials with each of the given filter types. You can specify a comma-separated list, or a range of values. E.g. -f 0-3 is the same as -f 0,1,2,3.

PNG delta filters (apply the same filter to every line):

0  =>  None      (recommended to always include this filter)
1  =>  Sub
2  =>  Up
3  =>  Average
4  =>  Paeth

Heuristic strategies (try to find the best delta filter for each line):

5  =>  MinSum    Minimum sum of absolute differences
6  =>  Entropy   Smallest Shannon entropy
7  =>  Bigrams   Lowest count of distinct bigrams
8  =>  BigEnt    Smallest Shannon entropy of bigrams
9  =>  Brute     Smallest compressed size (slow)

The default value depends on the optimization level preset.

  • --fast — Perform a fast compression evaluation of each enabled filter, followed by a single main compression trial of the best result. Note that this is enabled by default and will only be disabled at level 5 or above.
  • --zc <level> — Deflate compression level (0-12) for main compression trials. The levels here are defined by the libdeflate compression library.

The default value depends on the optimization level preset.

  • --nb — Do not change bit depth.
  • --nc — Do not change color type.
  • --np — Do not convert to indexed and do not modify an existing color palette.
  • --ng — Do not change to or from grayscale.
  • --nx — Do not perform any transformations and do not deinterlace by default.
  • --nz — Do not recompress IDAT unless required due to transformations. Recompression of other compressed chunks (such as iCCP) will also be disabled. ⚠️ Note that the combination of --nx and --nz will fully disable all optimization. Like, she's just standing there.
  • --fix — Do not perform checksum validation of PNG chunks. This may allow some files with errors to be processed successfully. The output will always have correct checksums. Healing era. 💖
  • --force — Write the output even if it is larger than the input. Sometimes you just need her to do it anyway.
  • -z, --zopfli — Use the much slower but stronger Zopfli compressor for main compression trials. Recommended use is with -o max and --fast. Slow and thorough, like a proper skincare routine.
  • --zi <iterations> — [default: 15] — Set the number of iterations to use for Zopfli compression. Using fewer iterations may speed up compression for large files. This option requires --zopfli to be set.
  • --ziwi <iterations> — Stop Zopfli compression after this number of iterations without improvement. Use this in conjunction with a high value for --zi to achieve better compression in reasonable time. Patience with boundaries. 💅
  • --brute-level <level> — Set the libdeflate compression level to use with the Brute filter strategy. Sane values are 1-5. Higher values are not necessarily better.
  • --brute-lines <lines> — Set the number of lines to compress at once with the Brute filter strategy. Sane values are 2-16. Higher values are not necessarily better.
  • --timeout <secs> — Maximum amount of time, in seconds, to spend on optimizations. Oxipng will check the timeout before each transformation or compression trial, and will stop trying to optimize the file if the timeout is exceeded. Note that this does not cut short any operations that are already in progress, so it is currently of limited effectiveness for large files with high compression levels. She's polite about it but she can't teleport.
  • --max-raw-size <bytes> — Maximum size to allow for the input image. If the raw, decompressed image data (or the file size) of the image exceeds this size, it will be skipped. This is useful for limiting memory usage or avoiding long processing times on large images. The value may be specified with a unit suffix such as k, KB, m, MB, etc.

The decompressed size of an image is roughly equal to width * height * bit-depth / 8. E.g. a 1920x1080 image with 24-bit color depth would be roughly 6MB. Math queen. 🧮

  • -t, --threads <num> — Set the maximum number of threads to use. Oxipng uses multithreading to evaluate multiple optimizations on the same file in parallel as well as process multiple files in parallel. You can set this to a lower value if you need to limit memory or CPU usage.

[default: num logical CPUs]

  • --sequential — Process multiple files sequentially rather than in parallel. Use this if you need determinism in the processing order. Note this is not necessary if using --threads 1. Control freak approved. 🎀
  • -h, --help — Print help (see a summary with -h).
  • -V, --version — Print version.
  • <files> — File(s) to compress. Use - for stdin. 🫶

🌈 VERSION 🌈

v10.2.1 — she's at her big girl version era.

👑 AUTHORS 👑

Joshua Holmer <jholmer.in@gmail.com> — the icon behind the icon. We stan. 💖

So yeah, that's oxipng bestie manual, version 10.2.1, dated 2026-09-02. Go forth and compress. Slay those PNGs. Periodt. 💅✨

📦 where this page comes from