cwebp Command-Line Tool: Full Reference

cwebp is Google's official command-line encoder for WebP, shipped in the libwebp package. It converts JPEG, PNG, and TIFF images to WebP with full control over quality, compression mode, and encoder effort. This guide is a practical reference to its most useful options, with examples for each.

For the format itself, see What is WebP?. To encode without installing anything, use PNG to WebP and JPG to WebP.

What is cwebp?

cwebp is the reference WebP encoder maintained by Google as part of the libwebp library. It reads a source image and writes a .webp file, exposing every encoder parameter that affects size and quality. It is the tool most other WebP encoders wrap internally.

cwebp accepts PNG, JPEG, TIFF, and WebP input. Its decoder counterpart, dwebp, converts WebP back to other formats.

What is the basic cwebp command?

The basic command takes an input file, a quality value, and an output path. The -q flag sets lossy quality from 0 to 100, and -o names the output file.

cwebp -q 80 input.png -o output.webp

This encodes input.png as lossy WebP at quality 80. Without -o, cwebp writes to standard output, which is useful in pipelines.

How do you encode lossless WebP with cwebp?

Add the -lossless flag to produce a bit-perfect WebP. Lossless mode ignores -q for quality and instead uses -z (0–9) to trade encoding speed for compression. Use lossless for logos, icons, and screenshots.

cwebp -lossless input.png -o output.webp
cwebp -lossless -z 9 input.png -o output.webp   # maximum compression, slowest

The mode choice by content type is covered in Lossy vs Lossless Compression: When to Use Each for WebP.

What does near-lossless mode do?

Near-lossless mode pre-processes pixels so lossless encoding compresses 25–40% smaller while staying visually identical. The -near_lossless flag takes a value from 0 (maximum pre-processing) to 100 (none). It suits screenshots and document scans.

cwebp -near_lossless 60 input.png -o output.webp

The encoding mechanics are explained in WebP Compression: How VP8 and VP8L Encoding Works.

What is the method (-m) option?

The -m option sets encoder effort from 0 (fastest) to 6 (slowest, smallest). Higher values spend more CPU searching for better compression. Use -m 6 for production assets encoded once, and lower values for time-sensitive batch work.

cwebp -q 80 -m 6 input.jpg -o output.webp

Encoding happens once; serving happens millions of times — -m 6 is almost always worth it for published images.

What are cwebp presets?

The -preset option applies tuned defaults for a content type before other flags are read. The six presets are default, photo, picture, drawing, icon, and text. A preset sets internal parameters suited to that content, which you can still override.

cwebp -preset photo -q 82 input.jpg -o output.webp
cwebp -preset text -q 90 screenshot.png -o output.webp

Place -preset first, because it resets parameters that later flags then adjust.

How do you resize and control alpha with cwebp?

Use -resize to scale during encoding and -alpha_q to set alpha-channel quality. Resizing at encode time avoids a separate step, and -alpha_q controls transparency compression independently of colour.

Common options:

-resize <width> <height> — scale output; use 0 for one dimension to preserve aspect ratio.
-alpha_q <0-100> — alpha compression quality; 100 keeps it lossless.
-metadata <all|none|exif|icc|xmp> — choose which metadata to keep.
-mt — enable multi-threading for faster encoding.

cwebp -q 80 -resize 1200 0 -metadata none -mt input.jpg -o output.webp

Transparency handling is detailed in WebP Transparency: Alpha Channel in Lossy and Lossless Modes.

How do you convert many files with cwebp?

Wrap cwebp in a shell loop or pipe it through a parallel runner to convert a directory. cwebp itself processes one file per invocation, so batch work is a scripting task around it.

for f in *.jpg; do cwebp -q 80 -m 6 "$f" -o "${f%.jpg}.webp"; done

Full batch strategies — parallelism, build tools, and watch pipelines — are in Batch Converting Images to WebP: CLI and Automated Workflows.

Where to go from here

cwebp gives complete control over WebP encoding. For published assets, encode at -m 6 with a content-matched preset, and reach for the browser-based converters when you do not need a toolchain.