Tuning the WebP Encoder

WebP gives encoders more knobs than any common web image format. Most teams turn one — quality — and leave the rest at default. That is fine for a starting point and wrong for a production library. This guide walks through every encoder parameter that meaningfully affects output, what it does, and what to set it to.

For a higher-level performance walkthrough that sits above these settings, see WebP Optimisation. For the mode-choice question — lossy or lossless? — see Lossy vs Lossless.

The five compression modes

WebP supports five distinct encoding modes. Each has a different parameter surface.

Mode	Flag	Best for
Lossy	(default)	Photographs, screenshots, gradients
Lossless	-lossless	Logos, icons, line art, screenshots with text
Near-lossless	-near_lossless N	High-fidelity art that must compress hard
Alpha-only	-alpha_q N (with lossy/lossless)	Tuning transparency separately
Animated	-loop, -d, frames	Replacing animated GIFs

Choosing the mode is the first decision and it cascades. Lossy quality flags are ignored in lossless mode; lossless level flags are ignored in lossy mode. Get the mode right before tuning anything else.

Quality factor (-q)

The -q flag accepts 0–100 in lossy mode and is the highest-impact parameter.

• 0–50: heavy compression, visible artefacts. Useful only for decorative or thumbnail content where weight dominates.
• 50–70: thumbnail and below-the-fold territory. Look acceptable at small sizes.
• 70–85: production sweet spot for almost all photographic content.
• 85–95: archival quality. Diminishing returns above q=90 — file size grows much faster than visible improvement.
• 95–100: indistinguishable from lossless in most cases. Use lossless instead at this point.

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

In lossless mode, -q controls the speed/size trade-off rather than fidelity. Lower values are faster; higher values try harder to find redundancies.

Method (-m) — encoder effort

The -m flag controls how hard the encoder tries to compress, on a scale of 0–6. Default is 4. This is the most under-used flag in WebP encoding.

• -m 0: fastest, largest files. Useful for live thumbnail generation.
• -m 4: default. Reasonable balance.
• -m 6: slowest, smallest files. Typically 5–10% smaller than -m 4 at the same quality.

Encoding happens once, serving happens forever. In any build pipeline, -m 6 is the right setting. The few extra seconds at build time pay back across every page load.

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

Alpha quality (-alpha_q)

For images with transparency, the alpha channel is encoded separately and can use a different quality factor. The -alpha_q flag controls it, 0–100. Default is 100 (lossless alpha).

• Keep -alpha_q 100 when transparency edges must remain crisp (logos, icons, UI elements).
• Drop to -alpha_q 80–90 for soft-edged alpha (shadows, drop-out backgrounds on product photos) — saves noticeable bytes with no visible change.

cwebp -q 80 -alpha_q 90 -m 6 product.png -o product.webp

The alpha compression method is also tunable with -alpha_method 0 (none, fastest) or -alpha_method 1 (compressed, default). Stay on the default.

Preset profiles (-preset)

WebP ships with five tuned profiles for common content types:

cwebp -preset photo -q 80 input.jpg -o output.webp
cwebp -preset picture -q 80 input.jpg -o output.webp
cwebp -preset drawing -q 90 input.png -o output.webp
cwebp -preset icon -q 90 input.png -o output.webp
cwebp -preset text -q 90 screenshot.png -o screenshot.webp

• photo — outdoor / natural-light photography. Optimises for smooth gradients and detail.
• picture — indoor / studio photography. Similar to photo with slightly different tuning.
• drawing — hand-drawn or stylised illustration. Preserves linework.
• icon — small, detailed graphics. Preserves edges aggressively.
• text — screenshots with text overlays. Preserves character readability.

Presets adjust internal parameters like spatial noise shaping and segment count. They are a reasonable starting point if you cannot tune per image — but a well-tuned manual setting still wins.

Near-lossless mode (-near_lossless)

Near-lossless is a lossy mode that targets near-perfect fidelity. It accepts 0–100 where 0 is maximum preprocessing (biggest savings, slight quality loss) and 100 is effectively lossless. The useful range is 40–80.

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

The output is a lossy WebP that looks identical to the source at typical viewing conditions, but compresses 25–40% better than full lossless. Use this for high-fidelity content where lossless is too large and standard lossy is too aggressive — typically charts, screenshots with critical detail, or product imagery on white backgrounds.

Lossless level (-z)

In lossless mode, -z is analogous to -m. It accepts 0–9, where higher means more encoder effort and smaller output.

cwebp -lossless -z 9 logo.png -o logo.webp

-z 9 is the right setting in any production pipeline. It is slower than the default -z 6 but the file size win is consistent.

Filter strength (-f) and sharpness (-sharpness)

The deblocking filter smooths block boundaries that lossy compression introduces. Stronger filtering means smoother output but loses fine detail.

• -f 0 disables filtering — preserves detail, may show blocking artefacts at low quality.
• -f 60 (default) — balanced.
• -f 100 — maximum smoothing.

-sharpness (0–7, default 0) controls how aggressively the filter preserves edges. Higher values mean the filter is gentler around sharp edges, preserving them at the cost of more visible blocking elsewhere.

For photographic content, leave both at defaults. For content with hard edges (charts, illustrations) consider -sharpness 4 to preserve linework.

Spatial noise shaping (-sns)

-sns controls how the encoder distributes quality across the image, 0–100. Default is 50. Higher values dedicate more bits to areas the encoder predicts will be visually sensitive.

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

Tuning -sns is fiddly and rarely worth the effort outside of pixel-perfect work. The default is fine for almost everything.

Multi-pass encoding (-pass)

-pass accepts 1–10. With more passes, the encoder iterates to hit a target file size or quality more precisely. Useful when you need to hit a specific byte budget.

# Target ~50KB output
cwebp -q 80 -pass 6 -size 50000 -m 6 input.jpg -o output.webp

Combine with -size (target byte size) or -psnr (target PSNR quality) to get reproducible output sizes — handy when ad networks or marketplaces enforce maximum file size.

Choosing settings by content type

Content	Mode	Settings
Photo (hero)	Lossy	-q 82 -m 6 -preset photo
Photo (article body)	Lossy	-q 75 -m 6 -preset photo
Photo (thumbnail)	Lossy	-q 65 -m 6 -preset photo
Product on white	Lossy	-q 80 -alpha_q 90 -m 6 -preset picture
Screenshot with text	Near-lossless	-near_lossless 60 -m 6 -preset text
Logo / icon (transparent)	Lossless	-lossless -z 9
Line art / illustration	Lossless	-lossless -z 9 -preset drawing
Chart or diagram	Near-lossless	-near_lossless 60 -m 6
Decorative background	Lossy	-q 55 -m 6

This table is a starting point. Always spot-check the output against the source.

Tooling differences

The same WebP encoder library powers most tools, but parameter exposure varies.

cwebp (reference)

The official CLI from Google. Exposes every parameter. The right tool for one-off encoding and as the reference for what each flag does.

Sharp (Node.js)

Production-grade for build pipelines.

import sharp from "sharp";

await sharp("source.jpg")
  .resize({ width: 1200, withoutEnlargement: true })
  .webp({
    quality: 80,
    alphaQuality: 90,
    effort: 6,
    nearLossless: false,
    smartSubsample: true,
  })
  .toFile("output.webp");

Sharp's effort parameter maps to -m. smartSubsample: true enables higher-quality chroma subsampling — recommended for any content with fine colour detail.

ImageMagick

Familiar but not the encoder of choice for WebP. Use it for conversion only when WebP is one stage in a longer ImageMagick pipeline. Otherwise prefer Sharp or cwebp.

convert input.png -quality 80 -define webp:method=6 output.webp

Squoosh (browser / CLI)

Squoosh exposes the full parameter set with visual diff. Useful for interactive tuning before encoding to a build pipeline. For library-wide encoding, use cwebp or Sharp.

Reproducible build pipelines

Hard-coding parameters in scripts is brittle. Encode through a build configuration that tracks every parameter:

{
  "webp": {
    "lossy": { "quality": 80, "alphaQuality": 90, "effort": 6, "preset": "photo" },
    "nearLossless": { "quality": 60, "effort": 6 },
    "lossless": { "effort": 9 }
  }
}

Drive your encoder from a config file rather than ad-hoc flags. When you re-tune (and you will, every 12–18 months as content shifts), the change is one place and the new files invalidate cleanly. Pair this with content-hashed filenames so renamed files invalidate browser caches automatically — see the caching section of WebP Optimisation.

Inspecting your output

After encoding, verify what you produced. The webpinfo tool dumps the file structure:

webpinfo output.webp

Look for the compression type, dimensions, and presence of alpha. For visual diffs, Squoosh accepts two files and shows pixel-level differences. For statistical comparison, dssim (or any SSIM tool) gives a numeric similarity score against the source.

Where to go from here

• Lossy vs Lossless Compression — choosing the right mode for a given image
• WebP Browser Support — what you can ship today
• WebP Optimisation — the bigger performance picture
• WebP format overview — what each parameter is acting on
• Convert existing libraries: PNG to WebP, JPG to WebP, GIF to WebP

The right WebP compression setting for any image is the one that ships the smallest file with imperceptible quality loss for the viewing conditions it will actually be seen in. Every parameter in this guide is a lever toward that target.