Processing Options

Transformations live in the URL path. Each directive is name:arg1:arg2, and directives chain with /.

Unrecognised directive names are ignored rather than rejected, so a typo silently drops that transformation instead of failing the request. Invalid arguments to a known directive do return 400. Cover your URL-building code with tests.

Quick reference

Presets

preset:name

Presets provide a way to define reusable sets of processing options via the IMGFORGE_PRESETS environment variable. Instead of repeating complex transformation chains in every URL, reference a preset by name.

Example configuration:

export IMGFORGE_PRESETS="thumbnail=resize:fit:150:150/quality:80,banner=resize:fill:1200:300/quality:90"

URL usage:

/signature/preset:thumbnail/aHR0cHM6Ly9leGFtcGxlLmNvbS9pbWFnZS5qcGc   # base64 URL-safe
/signature/pr:banner/plain/https%3A%2F%2Fexample.com%2Fhero.jpg@webp  # plain URL with @extension

Behavior:

• The preset:name (or pr:name) directive expands to the preset's defined options at processing time.
• Multiple presets can be chained: /preset:base/preset:quality_high/encoded_url.
• URL-specific options override preset values when the same parameter appears in both.
• A preset named default automatically applies to every request before other options or presets.

Presets-only mode:

Set IMGFORGE_ONLY_PRESETS=true to restrict URLs to preset references only. Non-preset options will return 400 Bad Request. This is useful for enforcing strict governance over allowed transformations.

Both URL-safe base64 and plain/ source references work with presets; choose whichever format fits your signing helper.

See Presets for comprehensive preset documentation including patterns, examples, and best practices. Configuration reference available in Configuration.

Geometry & resizing

resize:type:width:height[:enlarge][:extend]

• Types – fill, fit, force, and auto. auto selects fill when orientations match and fit otherwise.
• Defaults – If width or height are omitted (or 0), imgforge preserves aspect ratio using the provided dimension. enlarge and extend default to false unless explicitly set.
• Enlarging – Without enlarge:true, target dimensions that exceed the original image are clamped to avoid upscale work. Combine with min-width/min-height when you want conditional enlargement.
• Extending – extend:true pads the canvas to the requested size after resizing but before padding. The background colour determines the filled area.

size

size and its aliases are shorthand for resize:fit. Width or height of 0 lets imgforge infer the missing dimension. Use the trailing arguments to flip enlarge or extend without switching to the long form.

width / height

Setting a single dimension implicitly enables fit resizing. These options influence fallback behaviour when no explicit resize directive exists. enlarge:false still applies unless you opt in globally via the enlarge directive.

resizing_type

resizing_type:fill (or similar) changes how implicit resizes behave. It affects width, height, size, and subsequent resize directives that omit the type. Place it before directives that rely on the mode to avoid surprises.

resizing_algorithm

The interpolation kernel used whenever the image is scaled — by resize, size, width, height, min-width, min-height, zoom, pixelate, and watermark scaling.

• nearest – copies the nearest pixel. Hard edges, no blending. For pixel art and sprites.
• linear – bilinear. Softens detail; fine for throwaway previews.
• cubic – bicubic. Smooth, without the ringing the lanczos kernels can produce.
• lanczos2 – sharp, with less ringing than lanczos3.
• lanczos3 – default. Sharpest; can show faint halos on high-contrast edges.

Pick on appearance rather than speed: the kernel is rarely where the processing time goes. Resizing Algorithms explains why, and which kernel suits which content.

gravity

Gravity defaults to ce. It influences:

• Cropping windows when fill or crop is used.
• Canvas alignment for extend.
• Watermark positioning when combined with the watermark option (gravity only applies if you omit an explicit watermark position).

imgforge accepts imgproxy's gravity anchors: ce, no, so, ea, we, noea, nowe, soea, and sowe.

Minimum dimensions & zoom

• min-width and min-height trigger an extra resize pass if the image is still smaller after primary resizing. This pass honours enlarge; if you want guaranteed minimums, set enlarge:true.
• zoom multiplies dimensions after resizing and minimum checks. Values < 1 shrink the image; values > 1 enlarge it even if enlarge is false.

padding

• Accepts 1, 2, or 4 integers representing pixels.
• Padding runs after resizing/extend, so it doesn’t influence aspect ratio.
• dpr scaling multiplies all padding values before rendering.
• Transparent padding respects the output format: JPEG outputs are flattened against the background colour.

Cropping & rotation

crop

crop:x:y:width:height executes before any resizing. Coordinates are absolute, so gravity has no effect. Use it to isolate a region of interest that subsequent resizes should operate on.

auto_rotate and rotate

• auto_rotate defaults to true, applying EXIF orientation automatically. Disable (auto_rotate:false) when you need the raw sensor orientation.
• rotate applies an explicit 90° multiple after auto-rotation and resizing. Non-right-angle values are ignored.
• flip runs after rotation and flips horizontally, vertically, or both depending on boolean arguments.

Output control

format

If omitted, imgforge keeps the source image's format (a PNG stays a PNG, preserving transparency; imgproxy-compatible). Set IMGFORGE_DEFAULT_FORMAT to a concrete format to fix the default instead (see Configuration); sources that can't be sniffed or that this libvips build can't encode fall back to JPEG. Provide an explicit format (webp, png, avif, etc.) or use the @extension suffix following the source URL to override per request. Some formats may not be available if libvips lacks support.

quality

Defaults to 85 for lossy codecs (JPEG, WebP, AVIF). quality is ignored for lossless formats such as PNG. Raising quality increases file size and processing time; lowering it can introduce artefacts.

format_quality

format_quality:webp:80:jpeg:90 supplies per-format defaults when quality is not set. Explicit quality always wins.

Encoder options

• max_bytes repeatedly lowers quality for supported lossy encoders until output fits the byte budget or reaches quality 1.
• strip_metadata and strip_color_profile map to libvips metadata retention controls for formats that expose them.
• jpeg_options maps to progressive JPEG, chroma subsampling, trellis quantization, overshoot deringing, optimized scans, and quant table controls.
• png_options maps to interlacing and palette quantization controls.
• webp_options maps to lossless, smart chroma subsampling, and encoder preset controls. Preset names outside libvips' own set (default, picture, photo, drawing, icon, text) are accepted in URLs but ignored by the encoder.
• avif_options maps to AVIF/HEIF chroma subsampling.

WebP, AVIF, HEIF, and GIF are encoded through the libvips save suffix (.webp[Q=80,keep=all] and friends) rather than the libvips crate's generated save bindings. Those bindings name encoder properties that only exist in libvips 8.16 and later — exact on webpsave, tune on heifsave, keep-duplicate-frames on gifsave — and an older libvips rejects the whole call with no property named ..., so nothing encodes. Ubuntu 24.04, the base of the published image, ships libvips 8.15.1, which is exactly that case. JPEG, PNG, and TIFF use the generated bindings; every property they name predates 8.15.

Formats also depend on what your libvips was compiled with. A build without an HEVC encoder advertises heif support but fails at encode time with Unsupported compression; AVIF, which uses a different codec, is unaffected.

background

Accepts RGB or RGBA hex (FFFFFF or FFFFFFFF). The colour fills areas introduced by extend or padding. When outputting JPEG, imgforge automatically flattens transparency against the background colour. Without a background, JPEG outputs fall back to black.

background also accepts imgproxy's R:G:B channel form. background_alpha can be supplied before or after background to set the alpha channel.

dpr

• Defaults to 1.0 and caps at 5.0.
• Scales the resize width, height, and padding. min-width and min-height are not scaled.
• Only values above 1.0 have any effect; the source-image safeguards are evaluated before this runs, so dpr cannot trip them.
• Combine with quality adjustments to tailor assets for HiDPI displays.

Effects

blur

Gaussian blur with sigma > 0 softens the image after resizing and padding. Values between 1 and 5 offer noticeable smoothing without obliterating detail.

sharpen

Enhances edge contrast. Apply after resizing to counteract softness introduced by downscaling. Overly large values can create haloes.

pixelate

Downsamples and rescales the image to create a mosaic effect. Use high values (40+) for anonymisation.

zoom

Listed earlier under geometry, but keep in mind it also affects the intensity of subsequent effects—zooming in increases the apparent blur or pixelation radius.

adjust, brightness, contrast, and saturation

adjust is parsed as brightness:contrast:saturation, matching imgproxy's meta-option shape. saturation is applied for RGB/RGBA images. brightness and contrast are accepted and validated for URL compatibility, but the current libvips Rust crate does not publicly expose the needed linear operation, so those two controls are not applied yet.

Watermarking

1. Add watermark:<opacity>:<position> to enable overlay. Opacity ranges from 0.0 (invisible) to 1.0 (solid). Position accepts the same anchors as gravity (e.g., soea).
2. Supply the watermark image via watermark_url:<base64url> or configure IMGFORGE_WATERMARK_PATH on the server (see Configuration for details). When both are present, the URL value wins.
3. Watermarks render after resizing, padding, and effects. Oversized or missing watermark assets fail the request with 400 Bad Request.

Cache control & concurrency

• cachebuster:<token> appends arbitrary data to the cache key. Change the token when you want to force reprocessing without altering transformations. See Caching for more details on cache behavior.
• raw bypasses the concurrency semaphore that ordinarily limits the number of simultaneous libvips jobs. Reserve it for high-priority tasks; uncontrolled usage can starve other requests.
• expires:<unix_timestamp> rejects stale URLs with 404.
• filename:<name> sets Content-Disposition; add :true when the filename is URL-safe Base64 encoded.
• return_attachment:true makes filename responses use attachment; otherwise they use inline.
• skip_processing, page, pages, and disable_animation are accepted for signed URL compatibility. Full multi-page and animation source loading is not yet implemented in the current single-image decode path.

Security overrides

max_src_resolution and max_src_file_size relax server-wide safeguards for a single request. They only take effect when IMGFORGE_ALLOW_SECURITY_OPTIONS=true is set (see Configuration for security settings). Use cautiously, preferably on trusted internal URLs.

When output does not match the URL

Because unknown directive names are silently ignored, an option that appears to do nothing is usually a spelling mistake. Check the name against the quick reference above, then check the order: Image Processing Pipeline documents which stage each directive runs in, and several surprises (padding after resize, gravity ignored by explicit crops, minimums overriding zoom) come from ordering rather than the directive itself.