Using Uploadcare from Django

The most important thing for us at Uploadcare is to make file uploading on the web really easy. Everyone is used to the routine work, related to allowing users upload their userpics or attach resumes: from installing image processing libraries to creating folder with right permissions to ensuring the server never goes down or out of space to enabling CDN. Feature like ability to simply use a picture from Facebook or manual cropping are much more burdensome, hence rare. Uploadcare's goal is to change the status quo.

A simple Uploadcare File Field can be added to an existing Django project in just a couple of simple steps. As a result, your users are going to be able to see the progress of the upload, choose files from Google Drive or Instagram, and edit form while files are uploading asynchornously.

Installing Uploadcare library

First of all, you have to install a pyuploadcare package. This is simply done using pip:

$ pip install pyuploadcare

You may have to use sudo for that (in that case, we recommend you to try virtualenv instead).

Django settings

Open your settings.py and add a dictionary with your keys. If you don't have an account yet, you can use demo keys, as in example. However, the files on demo account are regularly deleted, so create an account as soon as Uploadcare catches your fancy:

UPLOADCARE = {
    # Don't forget to change to real keys when it gets serious!

    'pub_key': 'demopublickey',
    'secret': 'demoprivatekey',
}

Model Fields

Uploadcare field in Django admin

To attach Uploadcare files to a model, you can use a FileField or ImageField:

from django.db import models

from pyuploadcare.dj import FileField, ImageField


class Candidate(models.Model):
    name = models.CharField(max_length=120)
    about = models.TextField()

    resume = FileField(blank=True, null=True)
    photo = ImageField(blank=True, null=True, manual_crop="")

    def __unicode__(self):
        return self.name

These fields play by common Django rules. South migrations are supported.

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:

Manual crop

Non-admin forms

Obviously, you would want to use Uploadcare field outside an admin. It's going to work just as well, but, however, you have to remember to add `` in the <head> tag of your page:

Uploadcare field in the wild

Using the files

After the file is uploaded, it should be used. If you need just a download link, using your field will suffice:

<a href="">Download resume</a>

You can also use our CDN modifiers. They work with any image uploaded to Uploadcare. If manual_crop was enabled, your modifiers are going to be applied to the image, cropped as specified during upload; otherwise, to the original:


photo = ImageField()

<img src="">
    – original image
<img src="-/scale_crop/200x300/center/">
    - original image, scaled down and cropped to fit into 200x300

photo = ImageField(manual_crop="")

<img src="">
    - original image, cropped as specified during upload
<img src="-/scale_crop/200x300/center/">
    - same as above, scaled down and cropped to fit into 200x300


photo = ImageField(manual_crop="2:3")

<img src="">
    - original image, cropped as specified during upload, with proportions 2:3
<img src="-/scale_crop/200x300/center/">
    - same as above, scaled down to fit into 200x300. As proportions are 2:3, no cropping is needed

photo = ImageField(manual_crop="200x300")

<img src="">
    - original image, cropped as specified during upload, with dimensions 200x300
<img src="-/resize/100x/">
    - same as above, but scaled to half of its' size (100x150)

Migration of existing files to Uploadcare

If you already have a database of images, you may want to start migration to Uploadcare. The simplest way to do it is to just keep all the old files where they are, and to upload all the new files to Uploadcare. Uploadcare uploading widget can help you with that by allowing using arbitrary URLs as its value.

To set your Uploadcare field's value to the URL of the old file, you can use the initial parameter of the Django form. It's really simple with Class-Based Views:

class CandidateUpdateView(UpdateView):
    model = Candidate
    success_url = '/'

    def get_initial(self):
        initial = super(CandidateUpdateView, self).get_initial()

        if self.object and self.object.photo_old and not self.object.photo:
            initial['photo'] = self.object.photo_old.url

        return initial

Now, as soon as the update page is opened, the old file will be uploaded to Uploadcare, allowing your user to check it out in our widget and replace or just re-crop it as she wants.

That's it!

As you can see, with Uploadcare, adding and working with a file field is just as simple as with a CharField. We're happy to be working to help you make your and your clients experience better. Try Uploadcare right now! And don't forget to add our iOS library to your mobile app.

All the code is available on GitHub: https://github.com/uploadcare/uc_django_tutorial

If you haven't found what you were looking for in these docs, try looking in our Knowledge Base.