Updated at Nov 2, 2018:
As suggested by @fapolloner, I've removed the manual
file handling. Updated the example using FileSystemStorage instead. Thanks!
In this tutorial you will learn the concepts behind Django file upload and how to handle file upload using model forms.
In the end of this post you will find the source code of the examples I used so you can try and explore.
This tutorial is also available in video format:
The Basics of File Upload With Django
When files are submitted to the server, the file data ends up placed in request.FILES.
It is mandatory for the HTML form to have the attribute enctype="multipart/form-data" set correctly. Otherwise the
request.FILES will be empty.
The form must be submitted using the POST method.
Django have proper model fields to handle uploaded files: FileField and ImageField.
The files uploaded to FileField or ImageField are not stored in the database but in the filesystem.
FileField and ImageField are created as a string field in the database (usually VARCHAR), containing the reference
to the actual file.
If you delete a model instance containing FileField or ImageField, Django will not delete the physical file,
but only the reference to the file.
The request.FILES is a dictionary-like object. Each key in request.FILES is the name from the <input type="file" name="" />.
Each value in request.FILES is an UploadedFile instance.
You will need to set MEDIA_URL and MEDIA_ROOT in your project’s settings.py.
In the development server you may serve the user uploaded files (media) using django.contrib.staticfiles.views.serve()
To access the MEDIA_URL in template you must add django.template.context_processors.media to your
context_processeors inside the TEMPLATES config.
Simple File Upload
Following is a minimal file upload example using FileSystemStorage. Use it just to learn about the flow of the
File Upload With Model Forms
Now, this is a way more convenient way. Model forms perform validation, automatically builds the absolute path for the
upload, treats filename conflicts and other common tasks.
About the FileField upload_to Parameter
See the example below:
Note the upload_to parameter. The files will be automatically uploaded to MEDIA_ROOT/documents/.
It is also possible to do something like:
A file uploaded today would be uploaded to MEDIA_ROOT/documents/2016/08/01/.
The upload_to can also be a callable that returns a string. This callable accepts two parameters, instance and
Download the Examples
The code used in this post is available on Github.