Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

pypm install django-thumbnailfield

How to install django-thumbnailfield

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install django-thumbnailfield
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
0.1.4 Available View build log
0.1.2 Available View build log
Windows (64-bit)
0.1.4 Available View build log
0.1.2 Available View build log
Mac OS X (10.5+)
0.1.4 Available View build log
0.1.2 Available View build log
Linux (32-bit)
0.1.4 Available View build log
0.1.2 Available View build log
Linux (64-bit)
0.1.4 Available View build log
0.1.2 Available View build log
Lastest release
version 0.1.4 on Mar 13th, 2012

django-thumbnailfield is a enhanced ImageField of Django

It has the follwing features

  • Using Django storage system to store the image (Not like other Thumbnail library)
  • Automatically remove previous file from storage
  • Automatically generate thumbnails
  • Automatically remove generated previous thumbnail files from storage
  • Easy to use custom method to generate thumbnails


sudo pip install django-thumbnailfield

Prepare to use

  1. Append 'thumbnailfield' to INSTALLED_APPS

  2. Set MEDIA_ROOT correctly. For example:

    MEDIA_ROOT = os.path.join(os.path.dirname(__file__), '../static')

Example mini blog app


    from django.db import models
    from django.contrib.auth.models import User

from thumbnailfield.fields import ThumbnailField

    class Entry(models.Model):
            PUB_STATES = (
                    ('public', 'public entry'),
                    ('protected', 'login required'),
                    ('private', 'secret entry'),
            pub_state = models.CharField('publish status', choices=PUB_STATES)
            title = models.CharField('title', max_length=140)
            body = models.TextField('body')

    # This is a usage of ThumbnailField.
    # You have to set ``patterns`` to generate thumbnails
    thumbnail = ThumbnailField(_('thumbnail'), upload_to='img/thumbnails', null=True, blank=True, patterns={
            # Pattern Format:
            #   <Name>: (
            #   (<square_size>,),       # with defautl process_method
            #   (<width>, <height>,),   # with default process_method
            #   (<width>, <height>, <method or method_name>),
            #   (<width>, <height>, <method or method_name>, <method options>),
            #   )
            # If Name is ``None`` that mean original image will be processed
            # with the pattern
            # Convert original image to sepia and resize it to 800x400 (original
            # size is 804x762)
            None: ((None, None, 'sepia'), (800, 400, 'resize')),
            # Create 640x480 resized thumbnail as large.
            'large': ((640, 480, 'resize'),),
            # Create 320x240 cropped thumbnail as small. You can write short
            # pattern if the number of appling pattern is 1
            'small': (320, 240, 'crop', {'left': 0, 'upper': 0}),
            # Create 160x120 thumbnail as tiny (use default process_method to
            # generate)
            'tiny': (160, 120),
            # These thumbnails are not generated while accessed. These can be
            # accessed with the follwoing code::
            #   entry.thumbnail.large
            #   entry.thumbnail.small
            #   entry.thumbnail.tiny
            #   # shortcut properties
            #   entry.thumbnail.large_file  # as entry.thumbnail.large.file
            #   entry.thumbnail.large_path  # as entry.thumbnail.large.path
            #   entry.thumbnail.large_url   # as entry.thumbnail.large.url
            #   entry.thumbnail.large.size  # as entry.thumbnail.large.size
            # ...


        <title>django-thumbnailfield example</title>
        <dd><img src="{{ MEDIA_URL }}{{ object.thumbnail }}"></dd>
        <dt>Thumbnail "large"</dt>
        <dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.large }}"></dd>
        <dt>Thumbnail "small"</dt>
        <dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.small }}"></dd>
        <dt>Thumbnail "tiny"</dt>
        <dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.tiny }}"></dd>

How to use custom process method

Create your own custom process method like below:

from thumbnailfield.process_methods import get_sepia_image
from thumbnailfield.process_methods import get_cropped_image
from thumbnailfield.exceptions import ThumbnailFieldPatternImproperlyConfigured

def get_sepia_and_cropped_image(img, width, height, **options):
    # do something with img
    img = get_sepia_image(img, None, None, **options)
    img = get_cropped_image(img, width, height, **options)
    return img
def _sepia_and_cropped_error_check(f, img, width, height, **options):
    # do some error check
    if 'left' not in options:
        raise ThumbnailFieldPatternImproperlyConfigured(f, "'left' is required")
    if 'upper' not in options:
        raise ThumbnailFieldPatternImproperlyConfigured(f, "'upper' is required")
# Apply error check function
# Error check is recommended if your process method required any options
# otherwise just forget about this.
get_sepia_and_cropped_image.error_check = _sepia_and_cropped_error_check

Use defined method in pattern like below:

# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
        'large': (400, 500, get_sepia_and_cropped_image, {'left': 0, 'upper': 0})
# ...

Or define the method in THUMBNAILFIELD_PROCESS_METHOD_TABLE and use as a string anme:

# settings.py
from thumbnailfield import DEFAULT_PROCESS_METHOD_TABLE
THUMBNAILFIELD_PROCESS_METHOD_TABLE['sepia_and_crop'] = get_sepia_and_cropped_image

# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
        'large': (400, 500, 'sepia_and_crop', {'left': 0, 'upper': 0})
# ...



Remove previous files (include original file) when new file is applied to the ThumbnailField.

Default: True


Used when no process_method is applied in process pattern.

Default: thumbnail


Used when no process_options is applied in process pattern.

Default: {'resample': Image.ANTIALIAS}


Used to determine thumbnail filename. root, filename, name and ext is passed to the string. The generated filename of the thumbnail named 'large' of '/some/where/test.png' will be /some/where/test.large.png in default.

Default: r"%(root)s/%(filename)s.%(name)s.%(ext)s"


Used to determine process method from string name. The key of this dictionary is a name of the method and value is a method.

thumbnail, resize, crop, grayscale and sepia are defined as default.

Default: See thumbnailfield.__init__.DEFAULT_PROCESS_METHOD_TABLE

Subscribe to package updates

Last updated Mar 13th, 2012

Download Stats

Last month:1

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.