imgproxykit¶

A typed Python toolkit for building imgproxy URLs.

Describe image transformations in Python and generate signed URLs for your imgproxy server. Reuse the same settings across product cards, avatars, and image previews.

Build your first URL¶

Install imgproxykit with Python 3.12 or newer:

uv poetry pip

uv add imgproxykit

poetry add imgproxykit

pip install imgproxykit

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

Note

The examples use imgproxy.example.com for your imgproxy server and originals.example.com for the original images. Replace these example addresses with your own.

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

# Public URL of your imgproxy server.
client = Client('https://imgproxy.example.com')
source_url = 'https://originals.example.com/photo.jpg'

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)

thumbnail_url is ready to use in an image’s src attribute or an API response. Reuse thumbnail with other source images to apply the same 300×300 crop and WebP format across your application.

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¶

Getting started walks through installation and your first image URLs.
User guide covers client configuration, transformations, variants, and processing options.
API Reference lists classes, arguments, types, and extension points.
Version history tracks releases and compatibility changes.