Resizing Algorithms

resizing_algorithm (or ra) picks the interpolation kernel libvips uses when scaling an image. It applies to every scaling step: resize, size, width, height, min-width, min-height, zoom, pixelate, and watermark scaling.

resizing_algorithm:<algorithm>
ra:<algorithm>

The default is lanczos3.

The algorithms

Algorithm	Kernel	Character
`nearest`	Nearest-neighbour	Copies the closest source pixel. Hard edges, no blending.
`linear`	Bilinear	Averages 4 neighbours. Soft, slightly blurry on detailed images.
`cubic`	Bicubic	Weighted average of 16 neighbours. Smooth, mild sharpening.
`lanczos2`	Lanczos, 2 lobes	Sharp, with less ringing than `lanczos3`.
`lanczos3`	Lanczos, 3 lobes	Sharpest. Can show faint halos on high-contrast edges.

Choosing one

Choose on how the output should look, not on speed — see A note on speed below.

lanczos3 (default) – photographic content, and anything a person will look at closely. Leave it alone unless you have a reason to change it.
lanczos2 – when lanczos3 produces visible halos around hard edges, such as text or line art over flat backgrounds.
cubic – smooth results without ringing. A reasonable choice for heavy downscales where sharpness is wasted.
linear – rarely the best answer for final output; it softens detail. Useful for throwaway previews.
nearest – pixel art, sprites, screenshots of UI, and anything where blending between pixels destroys the content. Never use it for photographs.

Upscaling exaggerates every kernel's character: nearest produces hard blocks, linear produces mush, and the lanczos kernels produce the sharpest result with the most ringing.

A note on speed

The kernel is not usually where the time goes. libvips downscales in stages — an integer shrink first, then a final reduce — so the kernel only touches the last part of the work. Decoding the source image is typically the larger cost, and for big downscales the kernel choice is often lost in the noise entirely.

Two consequences:

Switching to a "faster" kernel is not a meaningful optimisation. If processing is too slow, look at caching, source size, and IMGFORGE_WORKERS first — see Performance Tips.
Benchmark your own workload before assuming a kernel costs anything. Cost depends on the source format, the scale factor, and how much of the work happens in the shrink stage.

Examples

# Photograph, default kernel — no need to name it
/<sig>/resize:fit:1200:1200/quality:90/plain/https://example.com/photo.jpg

# Pixel art thumbnail: preserve hard pixel edges
/<sig>/ra:nearest/resize:fit:256:256/plain/https://example.com/sprite.png

# Logo over a flat background, avoiding lanczos3 ringing
/<sig>/ra:lanczos2/resize:fit:600:0/plain/https://example.com/logo.png

# Heavy downscale where ringing would be wasted detail
/<sig>/ra:cubic/resize:fit:150:150/quality:80/plain/https://example.com/large.jpg

The kernel also governs scaling that happens implicitly:

# pixelate, zoom, min-width, and watermark scaling all use the chosen kernel
/<sig>/ra:nearest/pixelate:8/plain/https://example.com/face.jpg
/<sig>/ra:lanczos2/resize:fit:300:300/min-width:500/plain/https://example.com/image.jpg
/<sig>/ra:cubic/resize:fit:800:600/watermark:0.7:soea/plain/https://example.com/photo.jpg

Troubleshooting

Output looks blurry. Move from linear to cubic or a lanczos kernel, and consider sharpen:1 to counteract the softening that any downscale introduces. Check that the source is large enough for the target size.

Output has halos or ringing around hard edges. Move from lanczos3 to lanczos2, or to cubic if it persists.

Output looks blocky. You are probably on nearest, or upscaling well beyond the source resolution.

Results differ between sizes. Set the kernel explicitly rather than relying on the default if you need identical treatment across a set of derived images.