Image uploader and cropping tool to create thumbnails at various aspect ratios.

0 2 74 27
  • Created: Oct. 19, 2011
  • Last Release: Nov. 22, 2019
  • Last Commit: Nov. 22, 2019


Build Status

Cropduster logo

django-cropduster is a project that makes a form field available that uses the Jcrop jQuery plugin . It is a drop-in replacement for django's ImageField and allows users to generate multiple crops from images, using predefined sizes and aspect ratios. django-cropduster was created by developers at The Atlantic . It is compatible with python 2.7 and 3.4, and Django versions 1.4 - 1.8.


The recommended way to install django-cropduster is from PyPI :

    pip install django-cropduster

Alternatively, one can install a development copy of django-cropduster from source:

    pip install -e git+git://

If the source is already checked out, use setuptools:

    python develop


To enable django-cropduster, "cropduster" must be added to INSTALLED_APPS in and you must include cropduster.urls in your django urlpatterns.


    # ...


urlpatterns = patterns('',
    # ...
    url(r'^cropduster/', include('cropduster.urls')),

Documentation & Examples

class Size(name, [label=None, w=None, h=None, auto=None,
    min_w=None, min_h=None, max_w=None, max_h=None, required=True])

Use Size to define your crops. The auto parameter can be set to a list of other Size objects that will be automatically generated based on the user-selected crop of the parent Size .

CropDusterField accepts the same arguments as Django's built-in ImageField but with an additional sizes keyword argument, which accepts a list of Size objects.

An example

from cropduster.models import CropDusterField, Size

class ExampleModel(models.Model):
        # array of Size objects for initial crop
        Size("large", w=210, auto=[
            # array of Size objects auto cropped based on container Size
            Size('larger', w=768),
            Size('medium', w=85, h=113),
            # more sub Size objects ...
        # more initial crop Size objects ...

    image = CropDusterField(upload_to="your/path/goes/here", sizes=MODEL_SIZES)

To get a dictionary containing information about an image within a template, use the get_crop templatetag:

{% load cropduster_tags %}

{% get_crop obj.image 'large' exact_size=1 as img %}

{% if img %}
    <img src="{{ img.url }}" width="{{ img.width }}" height="{{ img.height }}"
         alt="{{ img.caption }}" />
    {% if img.attribution %}
        {{ img.caption }} (credit: {{ img.attribution }})
    {% endif %}
{% endif %}


The django code is licensed under the Simplified BSD License . View the LICENSE file under the root directory for complete license and copyright information.

The Jcrop jQuery library included is used under the MIT License .