Getting started¶

Build a transformed image URL, then define reusable variants for your application. You will need an imgproxy server to serve the resulting URLs.

Installation¶

imgproxykit requires Python 3.12 or newer:

uv add imgproxykit

poetry add imgproxykit

pip install imgproxykit

docker run -d --rm \
  --name imgproxy-test \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/imgproxy/imgproxy:latest

Build a thumbnail¶

Connect Client to the local container and describe a thumbnail with Transform. The source is a public sample image; you can replace it with another image URL accessible to imgproxy:

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

# Address of the test imgproxy container.
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

thumbnail = Transform(
    Resize(width=300, height=300, mode='fill'),
    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 example prints a URL pointing to your local imgproxy server. Open it in your browser to view the 300×300 WebP thumbnail.

Build variants¶

To generate several sizes of the same image, define a set of transformations. Reuse client and source_url from above, keep quality and format in a base transformation, then unpack base.options into a complete transformation for each width:

from imgproxykit import Client, Transform

client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'

# Share quality and output format across all variants.
base = Transform(quality=85, format='webp')
products = {
    # Unpack shared options and add a width for each variant.
    'small': Transform(*base.options, width=320),
    'medium': Transform(*base.options, width=640),
    'large': Transform(*base.options, width=1280),
}
product_urls = client.variants(source=source_url, variants=products)

# Access a URL by its variant name.
print('Small:', product_urls['small'])
print('Medium:', product_urls['medium'])
print('Large:', product_urls['large'])

The example prints three URLs for widths of 320, 640, and 1280 pixels. Open them to compare the sizes; each image keeps the source proportions and uses the shared WebP format and quality setting.

docker stop imgproxy-test

You’ve learned how to build image URLs and variants. Next, explore client configuration and more ways to compose transformations.

Next steps¶

• Client — client configuration and signed URLs.

• Transformations — compose and reuse processing settings.

• Variants — reusable sets and typed variant names.