Django Widget


Besides required pub_key, secret settings there are optional settings, for example, widget_version or widget_build:

    'pub_key': 'demopublickey',
    'secret': 'demoprivatekey',
    'widget_version': '3.x',  // ~= 3.0 (latest)
    'widget_build': 'min',  // without jQuery
    'cdn_base': '',

PyUploadcare takes assets from Uploadcare CDN by default, e.g.:

<script src=""></script>

If you don’t want to use hosted assets you have to turn off this feature:

    # ...
    'use_hosted_assets': False,

In this case local assets will be used.

If you want to provide custom url for assets then you have to specify widget url:

    # ...
    'use_hosted_assets': False,
    'widget_url': '',

Uploadcare widget will use default upload handler url, unless you specify:

    # ...
    'upload_base_url' = '',

Model Fields

As you will see, with Uploadcare, adding and working with a file field is just as simple as with a TextField. To attach Uploadcare files to a model, you can use a FileField or ImageField. These fields play by common Django rules. South migrations are supported.


When you call your_model_form.is_valid() or call photo.full_clean() directly it invokes method automatically. In other cases you should store objects manually, e.g:

photo.photo_2x3 = File('a771f854-c2cb-408a-8c36-71af77811f3b')


FileField does not require an uploaded file to be any certain format.

from django.db import models

from import FileField

class Candidate(models.Model):

    resume = FileField()


ImageField requires an uploaded file to be an image. An optional parameter manual_crop enables, if specified, a manual cropping tool: your user can select a part of an image she wants to use. If its value is an empty string, the user can select any part of an image; you can also use values like "3:4" or "200x300" to get exact proportions or dimensions of resulting image. Consult widget documentation regarding setting up the manual crop:

from django.db import models

from import ImageField

class Candidate(models.Model):

    photo = ImageField(blank=True, manual_crop="")

Advanced widget options

You can pass any widget options via FileWidget‘s attrs argument:

from django import forms

from import FileWidget, ImageField

# optional. provide advanced widget options:
class CandidateForm(forms.Form):
    photo = ImageField(widget=FileWidget(attrs={
        'data-cdn-base': '',
        'data-image-shrink': '1024x1024',


FileGroupField allows you to upload more than one file at a time. It stores uploaded files as a group:

from django.db import models

from import FileGroupField

class Book(models.Model):

    pages = FileGroupField()


ImageGroupField allows you to upload more than one image at a time. It stores uploaded images as a group:

from django.db import models

from import ImageGroupField

class Gallery(models.Model):

    photos = ImageGroupField()