Getting started

Build your first imgproxy URL, add image transformations, and configure signing. 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

Your first URL

Create a client with your imgproxy server’s public address, then pass a source image URL to url():

from imgproxykit import Client

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

imgproxy_url = client.url(source=source_url)

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.

Tip

The result is a URL string. Building it makes no network requests: imgproxy fetches and processes the source image when someone requests that URL. The source must be accessible to your imgproxy server.

Without signing credentials, the client uses the unsafe marker. Your server must accept unsigned URLs for this example to work.

Add transformations

Use Transform to specify processing options. This example creates a 300 by 300 crop with WebP output:

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',
)

thumbnail_url = client.url(source=source_url, transform=thumbnail)

Options such as Resize accept several arguments. Scalar options such as format can be passed directly as keyword arguments to Transform. Imgproxy applies the processing options when serving the image.

Sign URLs

For a server with signature checking enabled, supply both key and salt when creating the client. Use the same hex-encoded values configured in the server’s IMGPROXY_KEY and IMGPROXY_SALT settings.

from imgproxykit import Client

client = Client(
    'https://imgproxy.example.com',
    # Replace with your imgproxy server's hex-encoded key and salt.
    key='736563726574',
    salt='73616c74',
)
source_url = 'https://originals.example.com/photo.jpg'

imgproxy_url = client.url(source=source_url)

The client replaces the unsafe marker with a signature generated from the URL path. Keep signing credentials in your application on the server.

Reuse a transformation

A Transform is immutable and can be reused for different source images. Keep a transformation for each image size your application needs:

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

client = Client('https://imgproxy.example.com')
# Reuse the same transformation for multiple source images.
thumbnail = Transform(
    Resize(width=300, height=300, mode='fill'),
    format='webp',
)

source_urls = [
    'https://originals.example.com/sneakers.jpg',
    'https://originals.example.com/backpack.jpg',
]
thumbnail_urls = [
    client.url(source=source_url, transform=thumbnail)
    for source_url in source_urls
]

Both URLs use the same resize and format options for different source images.

Next steps