Skip to main content

Django custom storage for Thumbor backend.

Project description

A Django custom storage for Thumbor.

Provides 2 custom storages classes: ThumborStorage and ThumborMigrationStorage.

Use ThumborMigrationStorage on an Imagefield that started with a classic FileSystemStorage you want to upgrade to Thumbor without migrating your old media. That way, Django continues to serve them from the file system until the image is changed.


pip install django-thumborstorage




Add django_thumborstorage in INSTALLED_APPS.

And set the following with your values:

# This may be a different host than THUMBOR_SERVER
# only reachable by your Django server.

Just set the storage parameter in the ImageField you want to manage with Thumbor:

from django_thumborstorage.storages import ThumborStorage

class Stuff(models.Model):
    def upload_path(instance, filename):
        return 'stuffs/%s' % filename
    photo = models.ImageField(upload_to=upload_path,
    photo_height = models.IntegerField(blank=True, null=True)
    photo_width = models.IntegerField(blank=True, null=True)

In the code

You can get the Thumbor uuid from the <ImageField> instance using:

This is useful to generate_url() with Django-thumbor when original files are stored on Thumbor. Thus, you can pass the key as url parameter.



  • Add support for Django 3.2.

Possible breaking change

The leading / in the path of the file stored in the database has been removed due to a breaking change introduced un Django 3.2.11.

That release handle seamlessly both pre-2.0.0 style (/image/…) and post-2.0.0 style paths (image/…) so there is not need to migrate your database to replace /image/… with image/….


  • Drop support for Django < 2.1 and Python 2.7, 3.4 and 3.5
  • Use GitHub actions for CI instead of Travis.


  • Drop support for Django < 1.11 and Python 3.4.
  • Remove mock from dependencies.


  • Fix readonly_to_rw_url() to manage suffix in the urls.


  • Handle status code of the Thumbor server response when posting an image.


  • Added experimental Python 3.4 support (Thanks to Charlie 123.)
  • Fixed broken support for Django < 1.7 (Thanks to Rizziepit.)
  • Added unicode support in file names (Thanks to Rizziepit.)


  • Add storages.readonly_to_rw_url(), a function to convert a read-only thumbor url in a rw url.


  • Use THUMBOR_SERVER to generate the original file url.

Backward imcompatibilities

  • THUMBOR_SERVER and THUMBOR_SECURITY_KEY are required in settings.


  • Add ThumborStorage.key(name) to retrieve the Thumbor uuid from the name.


Backward imcompatibilities

  • THUMBOR_WRITABLE_SERVER setting is replaced by THUMBOR_RW_SERVER since it is now used to retrieve the original file.


  • PUT

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-thumborstorage-2.0.0.tar.gz (122.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page