Resize Filter
resize-filter
Selects the resampling kernel used whenever an image is scaled. Every resize has to decide what color each output pixel takes from the input pixels around it, and the kernel is that decision. The default is lanczos2, which suits photographic content; resize-filter lets you override it when a different trade-off between sharpness, smoothness and edge fidelity is wanted.
The kernel applies to both upscales and downscales.
Accepted values
| Value | Aliases | Best for |
|---|---|---|
lanczos2 | — | Default. Photographic content. A good balance of sharpness and freedom from artifacts. |
lanczos3 | lanczos, photo, sharp | A sharper result than lanczos2, at the cost of more ringing around high-contrast edges. |
bicubic | cubic, catmull-rom | Smooth gradients with moderate sharpening. |
mitchell | graphic, soft | Softer output with less ringing. Useful for graphics and flat color. |
bilinear | linear | Fast and smooth, noticeably softer than the cubic and lanczos kernels. |
nearest | pixel | Hard edges with no interpolation. The right choice for pixel art, QR codes and screenshots of UI. |
Values are matched exactly and are case-sensitive. A value that matches nothing — including a correctly spelled kernel in the wrong case, such as NEAREST — is ignored, and the image renders with the default lanczos2 instead of returning an error.
Preserving hard edges
The clearest difference appears when scaling up. nearest repeats each source pixel as a solid block, keeping edges crisp, while the default interpolates between them and produces a smooth gradient. For pixel art, QR codes, barcodes and UI screenshots, that interpolation is usually unwanted.
Sharpness on a downscale
A downscale throws most of the source pixels away, and the kernel decides how the survivors are weighted. The difference is clearest on fine, high-contrast detail: the photograph below is reduced to a third of its width, which leaves the bridge’s suspender cables about one output pixel wide.
Drag the divider to wipe one render over the other, and use the rows beneath it to put any two values on either side. lanczos2 is the default kernel, and original is the full-resolution source with no reduction applied at all.


nearest takes a single source pixel per output pixel and ignores the rest, so a cable that falls between samples simply disappears and the ones that survive turn jagged. It is the wrong choice for downscaling a photograph, however well it works on an upscale. bilinear averages only the four nearest pixels, which blurs the cables into the sky. The cubic and lanczos kernels weight a wider neighborhood and hold them.
Comparing any kernel against original shows what the reduction itself costs: the cables and the city on the far shore are carried by a handful of pixels at this size, and a kernel can only decide how gracefully they are given up.
Comparing the smooth kernels
lanczos2, lanczos3, bicubic and mitchell separate by only a pixel or two of edge contrast, which is not visible at normal size. Each demo below downscales the same crop to 100px wide with the named kernel and then magnifies that result 5x with nearest, so the individual output pixels can be compared:
The sharper kernels keep more contrast at an edge, at the cost of a light and dark fringe beside it — ringing. The softer kernels trade that contrast away for a cleaner transition.
Intent names may be retuned
pixel, graphic, soft, photo and sharp describe what a kernel is for rather than naming it. Which kernel each maps to may be retuned over time, so use the kernel names — nearest, mitchell, lanczos3 and the rest — wherever the output must not change.
Resizing layers
Watermarks and blend layers have their own kernels, and do not inherit this one. A layer resizes with lanczos2 unless you set mark-resize-filter or blend-resize-filter for it, whatever resize-filter says for the base image — including when blend-size=inherit makes a blend layer take the base image’s sizing.
That independence is useful: a pixel-art badge can stay crisp while the photograph behind it resizes normally.
?w=800&mark=badge.png&mark-w=96&mark-resize-filter=nearestWhat the kernel does not affect
resize-filter applies to the output resize of the picture you asked for. These keep their own resampling, so the setting cannot change what they see:
- The analysis behind smart crops —
crop=faces,crop=entropy,crop=edges,crop=auto— and object detection. - The blurred backdrop of
fit=fillwithfill=blur. maskandappendimages.- The internals of effects such as shadows and reflections.
fm=icoandfm=pdf.
Animated images use the kernel on every frame. Video is not affected.
Notes
resize-filter only takes effect when the image is actually scaled. A request that returns the image at its native size has nothing to resample, so the parameter makes no difference.
To enlarge a photograph rather than preserve hard pixels, consider super-resolution, which reconstructs detail instead of interpolating between existing pixels.




