Image uploader and cropping tool to create thumbnails at various aspect ratios
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


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.