Options¶

Options define individual processing settings, such as image dimensions, quality, and crop position. Import option classes from imgproxykit.options and combine their instances in a Transform. Simple settings can also be passed as keyword arguments.

Scalar options¶

Scalar options accept a single value. Pass an option instance to Transform, or use the equivalent keyword argument:

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

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

# Pass a scalar option instance or use its keyword form.
optimized = Transform(
    Quality(85),  # Equivalent to quality=85.
    format='webp',  # Equivalent to Format('webp').
)

# Build the URL; imgproxy processes the image when the URL is requested.
image_url = client.url(source=source_url, transform=optimized)

print(image_url)

Quality(85) and quality=85 create the same option, as do Format('webp') and format='webp'. Both forms can be used together in one transformation. Choose whichever fits how you organize your settings.

Structured options¶

Structured options group related settings in named arguments. For example, Resize combines dimensions and resizing mode, while Gravity selects the crop position:

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

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

# Combine structured options with a scalar keyword.
thumbnail = Transform(
    Resize(width=300, height=300, mode='fill'),
    Gravity(position='ce'),
    dpr=2,
)

# Build the URL; imgproxy processes the image when the URL is requested.
thumbnail_url = client.url(source=source_url, transform=thumbnail)

print(thumbnail_url)

Resize requests a 300×300 crop, Gravity(position='ce') keeps the center, and dpr=2 requests twice the pixel density. Pass structured options as positional arguments to Transform; scalar keywords can follow them.

Omitted arguments use imgproxy’s defaults. For example, leaving Resize.enlarge unset lets the server decide whether to upscale a small source. Explicit False and zero values are preserved.

Server presets¶

Preset references processing settings defined on the imgproxy server. Pass preset names as positional arguments and combine them with other options:

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

# Public URL of your imgproxy server.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

# Combine server presets with explicit processing options.
thumbnail = Transform(
    Preset('thumbnail', 'small'),
    quality=85,
    format='webp',
)

# Build the URL; imgproxy processes the image when the URL is requested.
thumbnail_url = client.url(source=source_url, transform=thumbnail)

print(thumbnail_url)

The guide’s Docker server defines thumbnail as a 300×300 crop and small as a 96×96 crop. This example references both presets in that order and requests quality 85 and WebP output. Imgproxy resolves their settings; the library sends the preset names without loading or expanding their definitions.

Available options¶

Built-in options cover resizing and cropping, formats and quality, effects, metadata, source limits, and URL behavior. For example, Blur adds blur, Background sets a background color, and Filename sets the download filename. See the Options API reference for the full list and constructor arguments.

Some options require server configuration. For example, source limit options require IMGPROXY_ALLOW_SECURITY_OPTIONS=true. Supported formats and processing features depend on your imgproxy installation; type annotations do not check server capabilities. See the imgproxy configuration documentation for server settings.

Next steps¶

Continue with Variants to generate named sets of image URLs. See the Options API reference for all processing options and their arguments.