imgproxykit

A typed Python toolkit for building imgproxy URLs.

Define reusable image transformations, generate signed URLs, and create named variants for thumbnails, avatars, and previews.

Build your first URL

Install imgproxykit with Python 3.12 or newer:

uv add imgproxykit

poetry add imgproxykit

pip install imgproxykit

Create a client pointing to your imgproxy server and define a thumbnail transformation:

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

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

thumbnail = Transform(
    Resize.fill(width=300, height=300),
    format='webp',
)

thumbnail_url = client.url(source=source_url, transform=thumbnail)  # (3)!
print(thumbnail_url)

  1. Public URL of your imgproxy server. Replace it with your own address.

  2. URL of the original image. Replace it with an image URL accessible to your imgproxy server.

  3. Build the URL without making a network request. Imgproxy fetches and processes the source image when the generated URL is requested.

Show Output
https://imgproxy.example.com/unsafe/resize:fill:300:300/format:webp/aHR0cHM6Ly9vcmlnaW5hbHMuZXhhbXBsZS5jb20vcGhvdG8uanBn

Use thumbnail_url in an image’s src attribute or an API response. Reuse thumbnail with other source images to apply the same transformation.

Tip

URL generation makes no network requests. Your imgproxy server fetches and processes the image when the generated URL is requested. You need a running imgproxy server to serve images.

Find your way