Skip to main content

Django Standarized Image Field

Project description

version codecov MIT License

Django Standardized Image Field

Django Field that implement the following features:

  • Django-Storages compatible (S3)
  • Resize images to different sizes
  • Access thumbnails on model level, no template tags required
  • Preserves original image
  • Asynchronous rendering (Celery & Co)
  • Restrict accepted image dimensions
  • Rename files to a standardized name (using a callable upload_to)


Simply install the latest stable package using the command

pip install django-stdimage
# or
pipenv install django-stdimage

and add 'stdimage' to INSTALLED_APPs in your, that's it!


StdImageField works just like Django's own ImageField except that you can specify different sized variations.

The JPEGField works similar to the StdImageField but all size variations are converted to JPEGs, no matter what type the original file is.


Variations are specified within a dictionary. The key will be the attribute referencing the resized image. A variation can be defined both as a tuple or a dictionary.


from django.db import models
from stdimage import StdImageField, JPEGField

class MyModel(models.Model):
    # works just like django's ImageField
    image = StdImageField(upload_to='path/to/img')

    # creates a thumbnail resized to maximum size to fit a 100x75 area
    image = StdImageField(upload_to='path/to/img',
                          variations={'thumbnail': {'width': 100, 'height': 75}})

    # is the same as dictionary-style call
    image = StdImageField(upload_to='path/to/img', variations={'thumbnail': (100, 75)})

    # variations are converted to JPEGs
    jpeg = JPEGField(
        variations={'full': (None, None), 'thumbnail': (100, 75)},

    # creates a thumbnail resized to 100x100 croping if necessary
    image = StdImageField(upload_to='path/to/img', variations={
        'thumbnail': {"width": 100, "height": 100, "crop": True}

    ## Full ammo here. Please note all the definitions below are equal
    image = StdImageField(upload_to='path/to/img', blank=True, variations={
        'large': (600, 400),
        'thumbnail': (100, 100, True),
        'medium': (300, 200),
    }, delete_orphans=True)

For using generated variations in templates use myimagefield.variation_name.


<a href="{{ object.myimage.url }}"><img alt="" src="{{ object.myimage.thumbnail.url }}"/></a>


Since version 4 the custom upload_to utils have been dropped in favor of Django Dynamic Filenames.


The StdImageField doesn't implement any size validation. Validation can be specified using the validator attribute and using a set of validators shipped with this package. Validators can be used for both Forms and Models.


from django.db import models
from stdimage.validators import MinSizeValidator, MaxSizeValidator
from stdimage.models import StdImageField

class MyClass(models.Model):
    image1 = StdImageField(validators=[MinSizeValidator(800, 600)])
    image2 = StdImageField(validators=[MaxSizeValidator(1028, 768)])

CAUTION: The MaxSizeValidator should be used with caution. As storage isn't expensive, you shouldn't restrict upload dimensions. If you seek prevent users form overflowing your memory you should restrict the HTTP upload body size.

Deleting images

Django dropped support for automated deletions in version 1.3.

Since version 5, this package supports a delete_orphans argument. It will delete orphaned files, should a file be delete or replaced via Django form or and object with a StdImageField be deleted. It will not be deleted if the field value is changed or reassigned programatically. In those rare cases, you will need to handle proper deletion yourself.

from django.db import models
from stdimage.models import StdImageField

class MyModel(models.Model):
    image = StdImageField(
        variations={'thumbnail': (100, 75)},

Async image processing

Tools like celery allow to execute time-consuming tasks outside of the request. If you don't want to wait for your variations to be rendered in request, StdImage provides your the option to pass a async keyword and a util. Note that the callback is not transaction save, but the file will be there. This example is based on celery.

from django.apps import apps

from celery import shared_task

from stdimage.utils import render_variations

def process_photo_image(file_name, variations, storage):
    render_variations(file_name, variations, replace=True, storage=storage)
    obj = apps.get_model('myapp', 'Photo').objects.get(image=file_name)
    obj.processed = True

from django.db import models
from stdimage.models import StdImageField

from .tasks import process_photo_image

def image_processor(file_name, variations, storage):
    process_photo_image.delay(file_name, variations, storage)
    return False  # prevent default rendering

class AsyncImageModel(models.Model):
    image = StdImageField(
        # above task definition can only handle one model object per image filename
        render_variations=image_processor  # pass boolean or callable
    processed = models.BooleanField(default=False)  # flag that could be used for view querysets

Re-rendering variations

You might want to add new variations to a field. That means you need to render new variations for missing fields. This can be accomplished using a management command.

python rendervariations 'app_name.model_name.field_name' [--replace] [-i/--ignore-missing]

The replace option will replace all existing files. The ignore-missing option will suspend missing source file errors and keep rendering variations for other files. Othervise command will stop on first missing file.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-stdimage, version 5.3.0
Filename, size File type Python version Upload date Hashes
Filename, size django_stdimage-5.3.0-py2.py3-none-any.whl (17.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size django-stdimage-5.3.0.tar.gz (13.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page