Django

Django is a Python web framework. Use imgproxykit’s shortcuts and template tags to generate image URLs and named variants from source strings and model file fields, with the client and reusable transformations configured in Django settings.

Explore the Django getting started guide and the project on GitHub.

Installation

In your Django project, install imgproxykit with Django support:

uv add 'imgproxykit[django]'

poetry add 'imgproxykit[django]'

pip install 'imgproxykit[django]'

To use template tags, add the integration to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'imgproxykit.integrations.django',
]

Tip

Adding the integration to INSTALLED_APPS is only required for template tags.

Configuration

Define IMGPROXYKIT in your Django settings:

from imgproxykit import Transform
from imgproxykit.integrations.django import SettingsDict

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

IMGPROXYKIT: SettingsDict = {
    'client': {  # (1)!
        'base_url': 'https://imgproxy.example.com',
        'key': '736563726574',  # (2)!
        'salt': '73616c74',
    },
    'transforms': {'thumbnail': thumbnail},  # (3)!
    'variants': {  # (4)!
        'product': {
            'small': thumbnail,
            'large': Transform(width=1280, format='webp'),
        },
    },
}

  1. Configure the shared client. base_url is required.

  2. Use your server’s hex-encoded key and salt, or omit both if the server accepts unsigned URLs.

  3. Optional named transformations for Python shortcuts and template tags.

  4. Optional named sets of transformations for generating variants.

See Client for other client options.

Generate URLs

Use imgproxy_url with a source string or model file field and a transformation name from IMGPROXYKIT['transforms']:

from imgproxykit.integrations.django import imgproxy_url

source = 'https://media.example.com/products/42.jpg'
image_url = imgproxy_url(source, 'thumbnail')  # (1)!
print(image_url)

  1. Select IMGPROXYKIT['transforms']['thumbnail'].

Show Output
https://imgproxy.example.com/UxKe7NsWROdmvXALKqYqE44cip98RhKENt4WIoAHQXY/width:300/height:300/format:webp/aHR0cHM6Ly9tZWRpYS5leGFtcGxlLmNvbS9wcm9kdWN0cy80Mi5qcGc

You can also pass a Transform object directly. Omit the transformation argument to generate a URL without processing options.

Generate variants

Use imgproxy_variants with a set name from IMGPROXYKIT['variants'] to generate several URLs for the same source:

from pprint import pprint

from imgproxykit.integrations.django import imgproxy_variants

source = 'https://media.example.com/products/42.jpg'
images = imgproxy_variants(source, 'product')  # (1)!
pprint(images, sort_dicts=False)

  1. Select IMGPROXYKIT['variants']['product'] and generate a URL for each configured name.

Show Output
{'small': 'https://imgproxy.example.com/UxKe7NsWROdmvXALKqYqE44cip98RhKENt4WIoAHQXY/width:300/height:300/format:webp/aHR0cHM6Ly9tZWRpYS5leGFtcGxlLmNvbS9wcm9kdWN0cy80Mi5qcGc',
 'large': 'https://imgproxy.example.com/katv-lzR6v0QJXwnIqDA0Bl9pTMy7IOxOXCDbWX99-4/width:1280/format:webp/aHR0cHM6Ly9tZWRpYS5leGFtcGxlLmNvbS9wcm9kdWN0cy80Mi5qcGc'}

The result is a dictionary of URLs with the configured variant names as keys. You can also pass a dictionary of names and Transform objects directly instead of a set name.

Templates

Warning

Add 'imgproxykit.integrations.django' to INSTALLED_APPS before using the template tags.

Load imgproxykit in your template, then use imgproxy_url to display an image with the thumbnail transformation configured above:

{% load imgproxykit %}

{% if product.image %}
  <img src="{% imgproxy_url product.image 'thumbnail' %}" alt="{{ product.name }}">
{% endif %}

The source can be a model file field, as shown here, or a source string. The transformation name is optional; omitting it generates a URL without processing options.

For a preview that links to a larger image, use imgproxy_variants with the configured product variant set:

{% load imgproxykit %}
{% if product.image %}
  {% imgproxy_variants product.image 'product' as images %}
  <a href="{{ images.large }}">
    <img src="{{ images.small }}" alt="{{ product.name }}">
  </a>
{% endif %}

Source resolution

By default, strings are passed unchanged and model file fields use .url. Relative URLs are not expanded automatically.

Configure IMGPROXY_BASE_URL on imgproxy, or set IMGPROXYKIT['source_resolver'] to resolve sources in Django. The resolver receives the original string or file field and must return a URI accessible to imgproxy.

Define a resolver in myapp/images.py:

from urllib.parse import urljoin

from django.db.models.fields.files import FieldFile


def resolve_image_source(source: str | FieldFile) -> str:
    """Return an absolute source URL for a string or model file field."""
    url = source.url if isinstance(source, FieldFile) else source
    return urljoin('https://media.example.com/', url)  # (1)!


print(resolve_image_source('/media/photo.jpg'))
print(resolve_image_source('https://storage.example.com/photo.jpg'))

  1. Resolve relative paths against the media domain. Absolute URLs keep their own domain.

Show Output
https://media.example.com/media/photo.jpg
https://storage.example.com/photo.jpg

Register the resolver in your Django settings:

IMGPROXYKIT = {
    # ...
    'source_resolver': 'myapp.images.resolve_image_source',
}

The setting also accepts a callable directly instead of an import path.

Next steps