Phew, Django documentation really does not have good example about this. I spent over 2 hours to dig up all the pieces to understand how this works. With that knowledge I implemented a project that makes possible to upload files and show them as list. To download source for the project, visit https://github.com/axelpale/minimal-django-file-upload-example or clone it:

> git clone https://github.com/axelpale/minimal-django-file-upload-example.git

Update 2013-01-30: The source at GitHub has also implementation for Django 1.4 in addition to 1.3. Even though there is few changes the following tutorial is also useful for 1.4.

Update 2013-05-10: Implementation for Django 1.5 at GitHub. Minor changes in redirection in urls.py and usage of url template tag in list.html. Thanks to hubert3 for the effort.

Update 2013-12-07: Django 1.6 supported at GitHub. One import changed in myapp/urls.py. Thanks goes to Arthedian.

Update 2015-03-17: Django 1.7 supported at GitHub, thanks to aronysidoro.

Update 2015-09-04: Django 1.8 supported at GitHub, thanks to nerogit.

Update 2016-07-03: Django 1.9 supported at GitHub, thanks to daavve and nerogit

Project tree

A basic Django 1.3 project with single app and media/ directory for uploads.

minimal-django-file-upload-example/    src/        myproject/            database/                sqlite.db            media/            myapp/                templates/                    myapp/                        list.html                forms.py                models.py                urls.py                views.py            __init__.py            manage.py            settings.py            urls.py

1. Settings: myproject/settings.py

To upload and serve files, you need to specify where Django stores uploaded files and from what URL Django serves them. MEDIA_ROOT and MEDIA_URL are in settings.py by default but they are empty. See the first lines in Django Managing Files for details. Remember also set the database and add myapp to INSTALLED_APPS

...import osBASE_DIR = os.path.dirname(os.path.dirname(__file__))...DATABASES = {    'default': {        'ENGINE': 'django.db.backends.sqlite3',        'NAME': os.path.join(BASE_DIR, 'database.sqlite3'),        'USER': '',        'PASSWORD': '',        'HOST': '',        'PORT': '',    }}...MEDIA_ROOT = os.path.join(BASE_DIR, 'media')MEDIA_URL = '/media/'...INSTALLED_APPS = (    ...    'myapp',)

2. Model: myproject/myapp/models.py

Next you need a model with a FileField. This particular field stores files e.g. to media/documents/2011/12/24/ based on current date and MEDIA_ROOT. See FileField reference.

# -*- coding: utf-8 -*-from django.db import modelsclass Document(models.Model):    docfile = models.FileField(upload_to='documents/%Y/%m/%d')

3. Form: myproject/myapp/forms.py

To handle upload nicely, you need a form. This form has only one field but that is enough. See Form FileField reference for details.

# -*- coding: utf-8 -*-from django import formsclass DocumentForm(forms.Form):    docfile = forms.FileField(        label='Select a file',        help_text='max. 42 megabytes'    )

4. View: myproject/myapp/views.py

A view where all the magic happens. Pay attention how request.FILES are handled. For me, it was really hard to spot the fact that request.FILES['docfile'] can be saved to models.FileField just like that. The model's save() handles the storing of the file to the filesystem automatically.

# -*- coding: utf-8 -*-from django.shortcuts import render_to_responsefrom django.template import RequestContextfrom django.http import HttpResponseRedirectfrom django.core.urlresolvers import reversefrom myproject.myapp.models import Documentfrom myproject.myapp.forms import DocumentFormdef list(request):    # Handle file upload    if request.method == 'POST':        form = DocumentForm(request.POST, request.FILES)        if form.is_valid():            newdoc = Document(docfile = request.FILES['docfile'])            newdoc.save()            # Redirect to the document list after POST            return HttpResponseRedirect(reverse('myapp.views.list'))    else:        form = DocumentForm() # A empty, unbound form    # Load documents for the list page    documents = Document.objects.all()    # Render list page with the documents and the form    return render_to_response(        'myapp/list.html',        {'documents': documents, 'form': form},        context_instance=RequestContext(request)    )

5. Project URLs: myproject/urls.py

Django does not serve MEDIA_ROOT by default. That would be dangerous in production environment. But in development stage, we could cut short. Pay attention to the last line. That line enables Django to serve files from MEDIA_URL. This works only in developement stage.

See django.conf.urls.static.static reference for details. See also this discussion about serving media files.

# -*- coding: utf-8 -*-from django.conf.urls import patterns, include, urlfrom django.conf import settingsfrom django.conf.urls.static import staticurlpatterns = patterns('',    (r'^', include('myapp.urls')),) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

6. App URLs: myproject/myapp/urls.py

To make the view accessible, you must specify urls for it. Nothing special here.

# -*- coding: utf-8 -*-from django.conf.urls import patterns, urlurlpatterns = patterns('myapp.views',    url(r'^list/$', 'list', name='list'),)

7. Template: myproject/myapp/templates/myapp/list.html

The last part: template for the list and the upload form below it. The form must have enctype-attribute set to "multipart/form-data" and method set to "post" to make upload to Django possible. See File Uploads documentation for details.

The FileField has many attributes that can be used in templates. E.g. {{ document.docfile.url }} and {{ document.docfile.name }} as in the template. See more about these in Using files in models article and The File object documentation.

<!DOCTYPE html><html>    <head>        <meta charset="utf-8">        <title>Minimal Django File Upload Example</title>       </head>    <body>    <!-- List of uploaded documents -->    {% if documents %}        <ul>        {% for document in documents %}            <li><a href="{{ document.docfile.url }}">{{ document.docfile.name }}</a></li>        {% endfor %}        </ul>    {% else %}        <p>No documents.</p>    {% endif %}        <!-- Upload form. Note enctype attribute! -->        <form action="{% url 'list' %}" method="post" enctype="multipart/form-data">            {% csrf_token %}            <p>{{ form.non_field_errors }}</p>            <p>{{ form.docfile.label_tag }} {{ form.docfile.help_text }}</p>            <p>                {{ form.docfile.errors }}                {{ form.docfile }}            </p>            <p><input type="submit" value="Upload" /></p>        </form>    </body></html> 

8. Initialize

Just run syncdb and runserver.

> cd myproject> python manage.py syncdb> python manage.py runserver

Results

Finally, everything is ready. On default Django developement environment the list of uploaded documents can be seen at localhost:8000/list/. Today the files are uploaded to /path/to/myproject/media/documents/2011/12/17/ and can be opened from the list.

I hope this answer will help someone as much as it would have helped me.

Generally speaking when you are trying to 'just get a working example' it is best to 'just start writing code'. There is no code here to help you with, so it makes answering the question a lot more work for us.

If you want to grab a file, you need something like this in an html file somewhere:

<form method="post" enctype="multipart/form-data">    <input type="file" name="myfile" />    <input type="submit" name="submit" value="Upload" /></form>

That will give you the browse button, an upload button to start the action (submit the form) and note the enctype so Django knows to give you request.FILES

In a view somewhere you can access the file with

def myview(request):    request.FILES['myfile'] # this is my file

There is a huge amount of information in the file upload docs

I recommend you read the page thoroughly and just start writing code - then come back with examples and stack traces when it doesn't work.

Demo

See the github repo, works with Django 3

A minimal Django file upload example

1. Create a django project

Run startproject::

$ django-admin.py startproject sample

now a folder(sample) is created.

2. create an app

Create an app::

$ cd sample$ python manage.py startapp uploader

Now a folder(uploader) with these files are created::

uploader/  __init__.py  admin.py  app.py  models.py  tests.py  views.py  migrations/    __init__.py

3. Update settings.py

On sample/settings.py add 'uploader' to INSTALLED_APPS and add MEDIA_ROOT and MEDIA_URL, ie::

INSTALLED_APPS = [    'uploader',    ...<other apps>...      ]MEDIA_ROOT = os.path.join(BASE_DIR, 'media')MEDIA_URL = '/media/'

4. Update urls.py

in sample/urls.py add::

...<other imports>...from django.conf import settingsfrom django.conf.urls.static import staticfrom uploader import views as uploader_viewsurlpatterns = [    ...<other url patterns>...    path('', uploader_views.UploadView.as_view(), name='fileupload'),]+ static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

5. Update models.py

update uploader/models.py::

from django.db import modelsclass Upload(models.Model):    upload_file = models.FileField()        upload_date = models.DateTimeField(auto_now_add =True)

6. Update views.py

update uploader/views.py::

from django.views.generic.edit import CreateViewfrom django.urls import reverse_lazyfrom .models import Uploadclass UploadView(CreateView):    model = Upload    fields = ['upload_file', ]    success_url = reverse_lazy('fileupload')    def get_context_data(self, **kwargs):        context = super().get_context_data(**kwargs)        context['documents'] = Upload.objects.all()        return context

7. create templates

Create a folder sample/uploader/templates/uploader

Create a file upload_form.html ie sample/uploader/templates/uploader/upload_form.html::

<div style="padding:40px;margin:40px;border:1px solid #ccc">    <h1>Django File Upload</h1>    <form method="post" enctype="multipart/form-data">      {% csrf_token %}      {{ form.as_p }}      <button type="submit">Submit</button>    </form><hr>    <ul>    {% for document in documents %}        <li>            <a href="{{ document.upload_file.url }}">{{ document.upload_file.name }}</a>            <small>({{ document.upload_file.size|filesizeformat }}) - {{document.upload_date}}</small>        </li>    {% endfor %}    </ul></div>

8. Syncronize database

Syncronize database and runserver::

$ python manage.py makemigrations$ python manage.py migrate$ python manage.py runserver

visit http://localhost:8000/