Skip to main content

django-upthor provides a django application for simple ajax file uploads.

Project description


django-upthor provides a django application for simple ajax file uploads. We use for the upload functionality.

Warning: This isn’t close to being a complete app, but it’s getting there.


Step 1. Install

  • pip install django-upthor

Now you have two options:

  • If you want to encrypt FQ values, install pycrypto. pip install pycrypto==2.6.1

  • Or you can, disable FQ encryption by adding THOR_DISABLE_FQ_ENCRYPT = True to your settings file.

Step 2. (Django 1.6+)

Add ‘upthor’ to your installed apps in



python migrate

Step 3. Use it in your app’s models.

import os
import uuid

from django.db import models
from upthor import fields as thor_fields

def random_upload_path(instance, filename):
    # Split the uuid into two parts so that we won't run into subdirectory count limits. First part has 3 hex chars,
    #  thus 4k possible values.
    uuid_hex = uuid.uuid4().hex
    return os.path.join(uuid_hex[:3], uuid_hex[3:], filename)

def post_example_file_link(real_instance, temporary_instance, raw_file):
        A callback called after linking the temporary file with the model.

        **Warning**: Don't call instances save method from here, cause it will cause an recursion error.

        @:param real_instance An instance of the model the file is attached to
        @:param temporary_instance An instance of TemporaryFileWrapper that the form links to.
        @:param raw_file The raw file that is being uploaded.

        @:return bool If True, the uploaded temporary file is removed once the linking is complete.
    return True

def get_file_image(file_path):
    """ An optional function that returns the display image html for files after uploading is complete"""

    return '<i class="fa fa-file"></i>'

class ExampleModelWithFile(models.Model):
    name = models.CharField(max_length=50)
    file = thor_fields.ThorFileField(upload_to=random_upload_path,
                                   allowed_types=['*'], widget=thor_fields.ThorSingleUploadWidget,

Step 4. Make sure to include form media.

Make sure you include the media files for the form in your templates:

E.g. Add the following codes where form is the context object of your modelform that uses the uploader fields.

{{ }}

{{ }}

Step 5. Add the upload url to your project urls.

url(r'', include('upthor.urls')),

Step 6. Optional stuff

Temporary file cleanup

If you want to clean up temporary files automatically, you’ll need to install django-cron and add upthor.cron.CleanTemporaryFiles to your cron classes in settings.

Alternatively to clean up manually you can use the management command clean_temporary_files.

Custom upload widget template

You can override ThorSingleUploadWidget.render_template to return your own widget template instead of the hardcoded one defined in Although the structure (including most classes) has to remain the same, there are a few data attributes on .file-upload that you can use to customize behavior:

Data Attribute Name





Required: URL to POST temporary files to, defaults to reverse of thor-file-upload.



Required: Maximum allowed file size in bytes, defaults to THOR_MAX_FILE_SIZE.



Required: Text to display if the file doesn’t meet the size requirements, defaults to "Uploaded file too large".



Whether or not to use background-image instead of img elements, defaults to false.


Currently it only supports local file backend, but we plan to add other backends when we reach a stable state.


The following settings are customizable using your django project settings file.


Path where the upload files will be stored. Defaults to “temp-files”.


How long to keep temporary files in the database and on disk. Defaults to “60*60*24”, e.g. 24 hours.


How long to keep linked temporary files in the database and on disk. Defaults to “60*60*6”, e.g. 6 hours.


The max file size of uploaded files. Defaults to “2*1024*1024”, e.g. 2 MB.


Disable the FQ Encryption, if this is False you need to install pycrypto since that is used for encryption. Defaults to “False”.


Should TemporaryFileWrapper model be shown in the admin interface. Defaults to “True”.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-upthor-0.9.1.tar.gz (14.7 kB view hashes)

Uploaded Source

Built Distribution

django_upthor-0.9.1-py3-none-any.whl (424.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page