Skip to main content

The easiest way to create thumbnails for your images with Django. Works with any storage backend.

Project description

# django-thumbs

Create thumbnails for your images with Django.

## Fork

Forked from <>.

## Features

* Easy to integrate in your code (no database changes, works as an `ImageField`)
* Works with any storage backend
* Generates thumbnails after image is uploaded into memory
* Deletes thumbnails when the image file is deleted
* Provides easy access to the thumbnails' URLs (similar method as with `ImageField`)

## Example

from django.db import models
from django_thumbs.fields import ImageThumbsField

class Person(models.Model):

{'code': 'avatar', 'wxh': '125x125', 'resize': 'crop'},
{'code': 'm', 'wxh': '640x480', 'resize': 'scale'},
{'code': '150', 'wxh': '150x150'}, # 'resize' defaults to 'scale'
photo = ImageThumbsField(upload_to='images', sizes=SIZES)

The field `photo` has a `sizes` attribute specifying desired sizes for the thumbnails. This field works the same way as `ImageField` but it also creates the desired thumbnails when uploading a new file and deletes the thumbnails when deleting the file.

With `ImageThumbsField` you retrieve the URL for every thumbnail specifying its size code. In this example we use ``, `` or `` to get the thumbnail URL.

## Install

Install django-thumbs into a virtualenv using pip:

(env)$ pip install git+

Add `thumbs` to your installed apps:

# ...

## Usage

* Import it in your `` and replace `ImageField` with `ImageThumbsField` in your model
* Add a `sizes` attribute with a list of sizes you want to use for the thumbnails
* Make sure you have defined `STATIC_URL` in your

## Sizes

Each size is a dictionary that defines a thumbnail. For example,

{'code': 'avatar', 'wxh': '125x125', 'resize': 'crop'},
{'code': 'm', 'wxh': '640x480', 'resize': 'scale'},
{'code': 'flatrow', 'wxh': 'x120'},
{'code': '150', 'wxh': '150x150'}, # 'resize' defaults to 'scale'

Size validation errors will raise `SizeError`.

### code (required)

matches re: `RE_CODE`

`code` is the size name. It appears in the thumb filename separated by `THUMBS_DELIMITER`. For example, `'original.jpg'` becomes `'original-small.jpg'` for the default delimiter `'-'` and code `'small'`.

### wxh (required)

matches re: `RE_WXH`

`wxh` is the width x height as a string.

Fixed width images are supported with `240x`. The thumbnail will be scaled
down *or up* to a 240 pixel width. Fixed height images are similarly
supported with `90x`.

### resize (optional)

default: `'scale'`
options: `'scale'` or `'crop'`

`resize` determines how the image will be resized.

`'scale'` resizes the thumb to `wxh`. For example, a 2000 x 1000 image will become 500 x 250 for `'scale'` and a `wxh` of `'500x500'`. `'scale'` does not enlarge a photo. A 200 x 100 image will remain 200 x 100 for `'scale'` and `wxh` of `'500x500'`. `'scale'` does not crop.

`'crop'` crops and centers the image fit `wxh` exactly. For example, a 2000 x 1000 image will become 500 x 500 for `'crop'` and a `wxh` of `'500x500'`. `'crop'` will enlarge a photo to exactly fit `wxh`. A 200 x 100 image will enlarge and crop to 500 x 500 for `'crop'` and `wxh` of `'500x500'`.

## Settings

`django-thumbs` will use default settings unless these settings are found in Django settings.


default: `'-'`

`THUMBS_DELIMITER` sets the delimiter between the original image base name and the thumb size `code`. For example, `'original.jpg'` becomes `'original-small.jpg'` for the default delimiter `'-'` and code `'small'`.


default: `False`

Set `THUMBS_JPG` to `True` to force all thumbnails to `.jpg` format and file extension regardless of original image format or file extension.


default: `75`

`THUMBS_QUALITY` sets PIL quality. See <>


default: `True`

`THUMBS_OPTIMIZE` sets PIL optimize option on JPG or PNG images.


default: `False`

`THUMBS_PROGRESSIVE` sets PIL progressive option on JPG images.


default: `True`

`THUMBS_AUTOROTATE` rotates thumbnails based on original EXIF data, if any.

## PublicS3BotoStorage

`PublicS3BotoStorage` generates clean URLs for Amazon S3 in code--without calling Amazon and without S3 querystring auth and expires. Hooray! URLs are `'public-read'`.

`PublicS3BotoStorage` is based on `S3BotoStorage_AllPublic` from <>.

Add to `requirements.txt`:


In Django settings, instead of

DEFAULT_FILE_STORAGE = 'storages.backends.s3boto.S3BotoStorage'

use `PublicS3BotoStorage`:

DEFAULT_FILE_STORAGE = 'django_thumbs.backends.PublicS3BotoStorage'

`PublicS3BotoStorage` looks for `AWS_S3_SECURE_URLS` and `AWS_S3_CUSTOM_DOMAIN` settings. `AWS_S3_SECURE_URLS` sets `https` or `http`. `AWS_S3_CUSTOM_DOMAIN` sets custom domain or ``.

## Uninstall

At any time you can go back and use `ImageField` again without altering the database or anything else. Just replace `ImageThumbsField` with `ImageField` again and make sure you delete the `sizes` attribute. Everything will work the same way it worked before using django-thumbs. Just remember to delete generated thumbnails in the case you don't want to have them anymore.

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-thumbs-v2-0.4.1.tar.gz (7.9 kB view hashes)

Uploaded source

Built Distributions

django_thumbs_v2-0.4.1-py3-none-any.whl (11.7 kB view hashes)

Uploaded py3

django_thumbs_v2-0.4.1-py2.py3-none-any.whl (11.7 kB view hashes)

Uploaded py2 py3

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