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 define a
thumbnail with Transform:
from imgproxykit import Client, Transform
from imgproxykit.options import Resize
client = Client('http://localhost:8080') # (1)!
source_url = 'https://picsum.photos/id/237/1600/1200' # (2)!
thumbnail = Transform(
Resize.fill(width=300, height=300),
format='webp',
)
thumbnail_url = client.url(source=source_url, transform=thumbnail) # (3)!
print(thumbnail_url)
Address of the local imgproxy container started above.
Public sample image. You can use another image URL accessible to your imgproxy server.
Generate a URL without making a network request. Imgproxy fetches and processes the source image when the generated URL is requested.
Show Output
http://localhost:8080/unsafe/resize:fill:300:300/format:webp/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Open the generated URL in your browser to view the image.
Build variants¶
Define a transformation for each size. Use
extend() to share quality and format across
variants:
from imgproxykit import Client, Transform
client = Client('http://localhost:8080')
source_url = 'https://picsum.photos/id/237/1600/1200'
base = Transform(quality=85, format='webp') # (1)!
products = {
'small': base.extend(width=320), # (2)!
'medium': base.extend(width=640),
'large': base.extend(width=1280),
}
product_urls = client.variants(source=source_url, variants=products)
print('Small:', product_urls['small'])
print('Medium:', product_urls['medium'])
print('Large:', product_urls['large'])
Shared quality and output format for all variants.
Add a width to the shared options without changing
base.
Show Output
Small: http://localhost:8080/unsafe/quality:85/format:webp/width:320/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Medium: http://localhost:8080/unsafe/quality:85/format:webp/width:640/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Large: http://localhost:8080/unsafe/quality:85/format:webp/width:1280/aHR0cHM6Ly9waWNzdW0ucGhvdG9zL2lkLzIzNy8xNjAwLzEyMDA
Each variant uses the shared quality and format with its own width. Open the generated URLs to compare them.
Tip
When finished, stop the test container:
docker stop imgproxy-test