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
Tip
To try the examples locally, start a test imgproxy container with Docker:
docker run -d --rm \
--name imgproxy-test \
-p 127.0.0.1:8080:8080 \
ghcr.io/imgproxy/imgproxy:latest
The examples below connect to this container at http://localhost:8080.
It accepts unsigned URLs without additional configuration.
See the imgproxy installation guide for other setup options.
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.
Tip
When finished, stop the test container:
docker stop imgproxy-test
You’ve learned how to build image URLs and variants. Next, explore client configuration and more ways to compose transformations.