Creating a Django app with Uploadcare
Uploadcare is an end-to-end file API that allows you to fully manage file uploading, storage, transformations, and delivery. All that is included in our Python and Django integrations.
In this guide, we'll create an app with an Instagram-like grid feed and image uploading:

pyuploadcare
is an official Uploadcare Python library providing wrappers for
file uploading, API interactions, and Image Transformations. In this guide,
we'll stick with using ImageField
, a File Uploader
implementation for Django.
Requirements
- Python 3.6+
- Django
If you're using pyuploadcare
with Django, check tox.ini
or
.github/workflows
for supported Python-Django combinations.
Installation
Our Python library, pyuploadcare
, consists of the Uploadcare API interface and
a couple of Django goodies. Although it isn’t necessary to go with Django, we'll
use it to build a sample project.
It’s a good practice to always use a per-project virtualenv when developing locally with Python. It's also a good way to get around the Python versions ambiguity. Generally, you create and activate a virtual environment this way:
pip install --upgrade virtualenv
cd instagrid # your project directory
# For Linux/MacOS
virtualenv --python python3 instagrid
source instagrid/bin/activate
# For Windows
virtualenv --python "c:\python36\python.exe" instagrid
.\instagrid\Scripts\activate
bash
If the commands worked out, your CLI prompt should change like this:
(instagrid) HostName:WorkingDirectory UserName$
bash
Now you can install Django and pyuploadcare
:
pip install django
pip install pyuploadcare
bash
Create a Django Project
Let’s start with creating the project:
django-admin startproject instagrid
cd instagrid
python manage.py runserver
bash
After running these three commands, open http://127.0.0.1:8000
in your
browser. You should already see the Django welcome screen:

Now stop the server using Ctrl+C
and run default Django migrations, which
Django asks to apply every time you run the server:
python manage.py migrate
bash
Configuration
Open the /instagrid/settings.py
file and find the INSTALLED_APPS
section.
There, add lines for your app name and pyuploadcare
:
INSTALLED_APPS = [
'instagrid',
'pyuploadcare.dj',
...
]
python
This, among other things, allows Django to look for models.py
in your
app’s directory.
Also, in the same file, find the definition of DIRS
in the TEMPLATES
section. Here we will add the path to the templates directory:
TEMPLATES = [
{
'DIRS': [os.path.join(BASE_DIR, 'templates')],
...
},
]
python
The last thing related to this file is your Uploadcare config. Put the API keys you discovered earlier in this guide somewhere in the file like another settings variable:
UPLOADCARE = {
'pub_key': 'YOUR_PUBLIC_KEY',
'secret': 'YOUR_SECRET_KEY',
}
WSGI_APPLICATION = ...
python
Creating a Model
Say, we would like to store the info about uploaded images in a database.
Create a new file under /instagrid/
named models.py
.
Here’s the sample model we will put there:
from django.db import models
from pyuploadcare.dj.models import ImageField
class Post(models.Model):
photo = ImageField(blank=True, manual_crop="")
python
ImageField is the pyuploadcare
implementation
of our File Uploader, which you can use as a regular
Django’s TextField.
Make and apply our app migrations to create a DB structure for the new model:
python manage.py makemigrations instagrid
python manage.py migrate
bash
Create a Template and a View
Now that we have done the groundwork for the app let’s make the app’s main page. It will serve as an image gallery and a place for the “Upload” button too.
We will not describe the process of building an HTML page. More tips on it you can easily find across the web.
Create the templates
folder under your project’s main directory (it’s near the
manage.py
), and put your index.html file there.
Open index.html
in your text editor, and note the following.
The form.media
here is a default Django form property which is going to
render any scripts needed for the form to work, in our case – Uploadcare
scripts:
<head>
<title>Instagrid</title>
{{ form.media }}
</head>
html
The following is the Django way of displaying forms:
<form action="" method="post">
{% csrf_token %}
{{ form }}
<input type="submit" value="Save"/>
</form>
html
And here is the part that renders uploaded images, which data are stored in DB. We’re using some capabilities of our Image Transformations to crop an image and define its quality:
{% if posts %}
{% for post in posts %}
<div class="col-md-4">
<img class="img-fluid" src="{{ post.photo.cdn_url }}-/crop/600x600/center/-/quality/lightest/" alt=""></div>
{% endfor %}
{% endif %}
html
The last thing in this step is creating a view. Views help Django know what template should be displayed and what data should be passed there.
Create a new file named views.py
under the /instagrid/
directory in your
app. Put there the following code:
from django.shortcuts import render, redirect
from .models import Post
from .forms import PostForm
def home(request):
if request.method == "POST":
form = PostForm(request.POST)
if form.is_valid():
post = form.save(commit=False)
post.save()
else:
form = PostForm()
try:
posts = Post.objects.all()
except Post.DoesNotExist:
posts = None
return render(request, 'index.html', { 'posts': posts, 'form': form })
python
This code is just slightly different from any basic tutorial’s one. Here we
define the home
view, which saves the form data on POST request and passes
all the objects stored in Post
DB.
To make view show up on the site, you have to also change the
/instagrid/urls.py
like that:
from django.contrib import admin
from django.urls import path
from . import views
urlpatterns = [
path('admin/', admin.site.urls),
path('', views.home)
]
python
Create a Form
We created a Post model in the first step and an index.html
template together
with the home
view in the second. To make them work together, we need to
implement the last component in our sample app – a form.
First, create the forms.py
file under the /instagrid/
directory in your
project.
The simplest way is to create a form from a model. Insert the following snippet into the newly created file:
from django import forms
from .models import Post
from pyuploadcare.dj.forms import ImageField
class PostForm(forms.ModelForm):
photo = ImageField(label='')
class Meta:
model = Post
fields = ('photo',)
python
You can read more about how these are built in Django Docs. One thing to note is the following line:
photo = ImageField(label='')
python
We set the label
to an empty string to ensure that we won’t have labels in our
form. Feel free to drop this argument if you like them 👍
Save all the edited files and run the server:
python manage.py runserver
bash
Now open http://127.0.0.1:8000
in your browser and play around with your
Instagrid application ✨

Next steps
There’s more to it: you can handle API requests and Image Transformations,
and enable the In-Browser Image Editing feature with pyuploadcare
too. To
continue your way with Uploadcare, take a look at these links: