The aim of django-cumulus is to provide a set of tools to utilize Rackspace Cloud Files through Django. It currently includes a custom file storage class, CloudFilesStorage.


To install the latest release from PyPI using pip:

pip install django-cumulus

To install the development version using pip:

pip install -e git://

Add cumulus to INSTALLED_APPS:



Add the following to your project’s file:

    'USERNAME': 'YourUsername',
    'API_KEY': 'YourAPIKey',
    'CONTAINER': 'ContainerName'

Alternatively, if you don’t want to set the DEFAULT_FILE_STORAGE, you can do the following in your models:

from import CloudFilesStorage

cloudfiles_storage = CloudFilesStorage()

class Photo(models.Model):
    image = models.ImageField(storage=cloudfiles_storage, upload_to='photos')
    alt_text = models.CharField(max_length=255)

Then access your files as you normally would through templates:

<img src="{{ photo.image.url }}" alt="{{ photo.alt_text }}" />

Or through Django’s default ImageField or FileField api:

>>> photo = Photo.objects.get(pk=1)
>>> photo.image.width
>>> photo.image.height
>>> photo.image.url

Static media

django-cumulus will work with Django’s built-in collectstatic management command out of the box. You need to supply a few additional settings:

    'STATIC_CONTAINER': 'YourStaticContainer'

Context Processor

django-cumulus includes an optional context_processor for accessing the full CDN_URL of any container files from your templates.

This is useful when you’re using Cloud Files to serve you static media such as css and javascript and don’t have access to the ImageField or FileField’s url() convenience method.

Add cumulus.context_processors.cdn_url to your list of context processors in your project’s file:


Now in your templates you can use {{ CDN_URL }} to output the full path to local media:

<link rel="stylesheet" href="{{ CDN_URL }}css/style.css">

Management commands


This management command synchronizes a local static media folder with a remote container. A few extra settings are required to make use of the command.

Add the following required settings:

    'STATIC_CONTAINER': 'MyStaticContainer', # the name of the container to sync with
    'SERVICENET': False, # whether to use rackspace's internal private network
    'FILTER_LIST': [] # a list of files to exclude from sync

Invoke the management command: syncstatic

You can also perform a test run: syncstatic -t

For a full list of available options: help syncstatic


This management command creates a new container in Cloud Files.

Invoke the management command: container_create <container_name>

For a full list of available options: help container_create


This management command deletes a container in Cloud Files.

Invoke the management command: container_delete <container_name>

For a full list of available options: help container_delete


This management command gathers information about containers in Cloud Files.

Invoke the management command: container_info [<container_one> <container two> ...]

For a full list of available options: help container_info


This management command lists all the items in a Cloud Files container to stdout.

Invoke the management command: container_list <container_name>

For a full list of available options: help container_list


Below are the default settings:

    'API_KEY': None,
    'AUTH_URL': 'us_authurl',
    'CNAMES': None,
    'CONTAINER': None,
    'SERVICENET': False,
    'TIMEOUT': 5,
    'MAX_RETRIES': 5,
    'TTL': 86400,
    'USE_SSL': False,
    'USERNAME': None,
    'FILTER_LIST': []


Required. This is your API access key. You can obtain it from the Rackspace Management Console.


Set this to the region your account is in. Valid values are us_authurl (default) and uk_authurl.


A mapping of ugly Rackspace URLs to CNAMEd URLs. Example:

    'CNAMES': {
        '': ''


Required. The name of the container you want files to be uploaded to.


A list of items to exclude when using the syncstatic management command. Defaults to an empty list.


Specifies whether to use Rackspace’s private network (True) or not (False). If you host your sites on Rackspace, you should set this to True in production as you will not incur data transfer fees between your server(s) and Cloud Files on the private network.


When using Django’s collectstatic or django-cumulus’s syncstatic command, this is the name of the container you want static files to be uploaded to.


The timeout to use when attempting connections to Cloud Files. Defaults to 5 (seconds).


The number of retry attempts that should be made when a connection or SSL error occurs while reading a file on the container. Defaults to 0. Set this to a higher value if you experience connectivity issues.


Additional keyword arguments to pass to the cloudfiles.Connection instance. Useful for debugging. Default is {}, an empty dict.


The maximum time (in seconds) until a copy of one of your files distributed into the CDN is re-fetched from your container. Defaults to 86400 (seconds) (24h), the default set by python-cloudfiles.

Note: After changing TTL, caching servers may not recognize the new TTL for this container until the previous TTL expires.


Whether or not to retrieve the container URL as http (False) or https (True).


Required. This is your API username. You can obtain it from the Rackspace Management Console.


Set headers based on a regular expression in the file name. This can be used to allow Firefox to access webfonts across domains:

    'HEADERS': (
        (r'.*\.(eot|otf|woff|ttf)$', {
            'Access-Control-Allow-Origin': '*'


  • Django>=1.2
  • python-cloudfiles >= 1.7.9


To run the tests, clone the github repo, install tox and invoke tox from the clone’s root. This will upload two very small files to your container and delete them when the tests have finished running.


To report issues, please use the issue tracker at