Processing options¶

Processing options describe the image you want imgproxy to produce. Import option classes from imgproxykit.options and collect them in a Transform. Scalar options can also be supplied as keyword arguments; see Transformations for both forms and their ordering.

This page groups common options by task. For accepted arguments and links to imgproxy’s processing documentation, see Processing options.

Dimensions and cropping¶

Use Resize to set dimensions and resizing mode. fit preserves the image within the requested bounds, while fill fills the requested dimensions by cropping. Use Gravity to choose the retained area.

from imgproxykit import Client, Transform
from imgproxykit.options import Gravity, Resize

client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/photo.jpg'

thumbnail = Transform(
    Resize(width=300, height=300, mode='fill'),
    Gravity(position='ce'),
    dpr=2,
)
thumbnail_url = client.url(source=source_url, transform=thumbnail)

Here, ce selects center gravity and dpr=2 requests twice the pixel density for the 300 by 300 target. Smaller sources are subject to imgproxy’s upscaling settings.

Related options:

• Width, Height, Size and ResizingType set individual sizing parameters.

• Enlarge controls upscaling; Extend and ExtendAspectRatio control extending the canvas.

• Crop, Zoom and Trim adjust the source area.

• MinWidth and MinHeight add sizing constraints.

• EnforceThumbnail selects an embedded HEIC or AVIF thumbnail when available.

• Padding adds space around the image; Background sets its color.

Format, quality, and metadata¶

Use Format or the format keyword to choose an output format, and Quality or quality to set encoding quality. A background color is useful when converting a transparent image to JPEG:

from imgproxykit import Client, Transform
from imgproxykit.options import Background

client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/logo.png'

jpeg = Transform(
    Background(color='ffffff'),
    format='jpg',
    quality=85,
    strip_metadata=True,
)
jpeg_url = client.url(source=source_url, transform=jpeg)

The example requests JPEG output with a white background, quality 85, and metadata stripping. Hex background colors omit the leading #.

Related options:

• FormatQuality sets quality for a particular format.

• MaxBytes sets a target maximum output file size.

• StripMetadata, KeepCopyright and StripColorProfile control metadata and color profile retention.

• PreserveHDR controls HDR preservation for supported outputs.

Effects and orientation¶

A small resize combined with Blur can produce a preview placeholder:

from imgproxykit import Client, Transform
from imgproxykit.options import Resize

client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/photo.jpg'

preview = Transform(
    Resize(width=32, height=32, mode='fit'),
    blur=2,
    format='webp',
)
preview_url = client.url(source=source_url, transform=preview)

Other options include Sharpen, Pixelate, AutoRotate, Rotate and Flip. Watermark applies an image configured on the imgproxy server; it does not upload a watermark image from your application.

Source and animation limits¶

Use per-request limits when different image sources need different bounds:

from imgproxykit import Client, Transform

client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/photo.jpg'

limited = Transform(
    max_src_resolution=20,
    max_src_file_size=5_000_000,
)
imgproxy_url = client.url(source=source_url, transform=limited)

This requests a source limit of 20 megapixels and 5,000,000 bytes.

Configure server-wide limits on imgproxy when per-request overrides are not needed.

URL behavior and presets¶

These options control behavior beyond image dimensions and encoding:

• Preset references named settings on the server. See Server presets for an example combining presets with other options.

• Expires sets an expiration time as a Unix timestamp in seconds.

• CacheBuster changes the URL to distinguish cached variants.

• Filename and ReturnAttachment control download-related behavior.

• Raw and SkipProcessing control serving the source without the usual processing; consult their API entries for the differences.

Omitted and explicit values¶

Omitted option arguments remain None and leave their values to imgproxy. Explicit False and zero values are preserved in the URL; they are not silently omitted. Booleans are serialized as 1 or 0.

Type annotations describe accepted argument types. They do not imply that every value is validated at runtime or that the server supports every option. Refer to each option’s documentation for its meaning and requirements.

Next steps¶

• Processing options — all built-in options and their arguments.

• Types — supported formats, positions, and other values.

• Transformations — reuse options and combine them with presets.