Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

440 lines (298 sloc) 14.321 kB
Django compressor
Compresses linked and inline JavaScript or CSS into a single cached file.
* Install django_compressor with your favorite Python package manager::
pip install django_compressor
* Add ``'compressor'`` to your ``INSTALLED_APPS`` setting::
# other apps
* See the list of settings_ to modify django_compressor's default behaviour.
* In case you use Django 1.3's staticfiles_ contrib app (or its standalone
clone django-staticfiles_) you have to add django_compressor's file finder
to the ``STATICFILES_FINDERS`` setting::
# other finders..
.. _staticfiles:
.. _django-staticfiles:
.. code-block:: django
{% load compress %}
{% compress <js/css> %}
<html of inline or linked JS/CSS>
{% endcompress %}
.. code-block:: django
{% load compress %}
{% compress css %}
<link rel="stylesheet" href="/static/css/one.css" type="text/css" charset="utf-8">
<style type="text/css">p { border:5px solid green;}</style>
<link rel="stylesheet" href="/static/css/two.css" type="text/css" charset="utf-8">
{% endcompress %}
Which would be rendered something like:
.. code-block:: django
<link rel="stylesheet" href="/static/CACHE/css/f7c661b7a124.css" type="text/css" charset="utf-8">
.. code-block:: django
{% load compress %}
{% compress js %}
<script src="/static/js/one.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">obj.value = "value";</script>
{% endcompress %}
Which would be rendered something like:
.. code-block:: django
<script type="text/javascript" src="/static/CACHE/js/3f33b9146e12.js" charset="utf-8"></script>
Linked files must be accesible via COMPRESS_URL_. If DEBUG is ``True``,
off-site files will throw exceptions. If DEBUG is ``False`` they will be
silently stripped.
If COMPRESS is ``False`` (defaults to the opposite of DEBUG) the ``compress``
template tag simply returns exactly what it was given, to ease development.
.. warning::
For production sites it is **strongly recommended** to use a real cache
backend such as memcached_ to speed up the checks of compressed files.
Make sure you set your Django cache backend appropriately (also see
COMPRESS_CACHE_BACKEND_ and Django's `caching documentation`_).
.. _memcached:
.. _caching documentation:
Remote storages
In some cases it's useful to use a CDN_ for serving static files such as
those generated by django_compressor. Due to the way django_compressor
processes files, it requires the files to be processed (in the
``{% compress %}`` block) to be available in a local file system cache.
django_compressor provides hooks to automatically have compressed files
pushed to a remote storage backend. Simply use set the COMPRESS_STORAGE_
setting to a storage backend that saves the result to a remote service.
So assuming your CDN is `Amazon S3`_, you can use the boto_ storage backend
from the 3rd party app `django-storages`_. Some required settings are::
AWS_STORAGE_BUCKET_NAME = 'compressor-test'
Next, you need to specify the new CDN base URL and update the URLs to the
files in your templates which you want to compress::
.. note::
For staticfiles just set ``STATIC_URL = COMPRESS_URL``
The storage backend to save the compressed files needs to be changed, too::
COMPRESS_STORAGE = 'storages.backends.s3boto.S3BotoStorage'
If you are using Django 1.3's staticfiles_ contrib app or the standalone
app django-staticfiles_, you'll need to use a temporary filesystem cache
for django_compressor to know which files to compress. Since staticfiles
provides a management command to collect static files from various
locations which uses a storage backend, this is where both apps can be
First, make sure the COMPRESS_ROOT_ and STATIC_ROOT_ settings are equal
since both apps need to look at the same directories when to do their job.
Secondly, you need to create a subclass of the remote storage backend
you want to use; below is an example of the boto S3 storage backend
from django-storages::
from import get_storage_class
from storages.backends.s3boto import S3BotoStorage
class CachedS3BotoStorage(S3BotoStorage):
S3 storage backend that saves the files locally, too.
def __init__(self, *args, **kwargs):
super(CachedS3BotoStorage, self).__init__(*args, **kwargs)
self.local_storage = get_storage_class(
def save(self, name, content):
name = super(CachedS3BotoStorage, self).save(name, content)
self.local_storage._save(name, content)
return name
dotted path of your custom cached storage backend,
e.g. ``''``.
To have Django correctly render the URLs to your static files, set the
``STATIC_URL`` setting to the same value as COMPRESS_URL_ (e.g.
.. _CDN:
.. _Amazon S3:
.. _boto:
.. _django-storages:
CSS Notes
All relative ``url()`` bits specified in linked CSS files are automatically
converted to absolute URLs while being processed. Any local absolute URLs (those
starting with a ``'/'``) are left alone.
Stylesheets that are ``@import``'d are not compressed into the main file.
They are left alone.
If the media attribute is set on <style> and <link> elements, a separate
compressed file is created and linked for each media value you specified.
This allows the media attribute to remain on the generated link element,
instead of wrapping your CSS with @media blocks (which can break your own
@media queries or @font-face declarations). It also allows browsers to avoid
downloading CSS for irrelevant media types.
* Use only relative or full domain absolute URLs in your CSS files.
* Avoid @import! Simply list all your CSS files in the HTML, they'll be combined anyway.
Why another static file combiner for Django?
Short version: None of them did exactly what I needed.
Long version:
**JS/CSS belong in the templates**
Every static combiner for Django I've seen makes you configure
your static files in your While that works, it doesn't make
sense. Static files are for display. And it's not even an option if your
settings are in completely different repositories and use different deploy
processes from the templates that depend on them.
django_compressor doesn't care if different pages use different combinations
of statics. It doesn't care if you use inline scripts or styles. It doesn't
get in the way.
**Automatic regeneration and cache-foreverable generated output**
Statics are never stale and browsers can be told to cache the output forever.
**Full test suite**
I has one.
Django compressor has a number of settings that control its behavior.
They've been given sensible defaults.
:Default: the opposite of ``DEBUG``
Boolean that decides if compression will happen.
:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions)
Controls the URL that linked files will be read from and compressed files
will be written to.
.. note::
This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL``
is not given or empty, e.g. on older Django versions (<1.3).
:Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions)
Controls the absolute file path that linked static will be read from and
compressed static will be written to when using the default COMPRESS_STORAGE_
.. note::
This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT``
is not given, e.g. on older Django versions (<1.3).
:Default: ``'CACHE'``
Controls the directory inside COMPRESS_ROOT_ that compressed files will
be written to.
:Default: ``['compressor.filters.css_default.CssAbsoluteFilter']``
A list of filters that will be applied to CSS.
:Default: ``['compressor.filters.jsmin.JSMinFilter']``
A list of filters that will be applied to javascript.
:Default: ``''``
The dotted path to a Django Storage backend to be used to save the
compressed files.
``compressor`` ships with one additional storage backend:
* ``''``
A subclass of the default storage backend, which will additionally
create ``*.gz`` files of each of the compressed files.
:Default: ``'compressor.parser.BeautifulSoupParser'``
The backend to use when parsing the JavaScript or Stylesheet files.
The backends included in ``compressor``:
- ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.LxmlParser``
See `Dependencies`_ for more info about the packages you need for each parser.
:Default: ``"default"`` or ``CACHE_BACKEND``
The backend to use for caching, in case you want to use a different cache
backend for compressor.
If you have set the ``CACHES`` setting (new in Django 1.3),
``COMPRESS_CACHE_BACKEND`` defaults to ``"default"``, which is the alias for
the default cache backend. You can set it to a different alias that you have
configured in your ``CACHES`` setting.
If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND``
setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting.
:Default: ``2592000`` (30 days in seconds)
The period of time after which the compressed files are rebuilt even if
no file changes are detected.
:Default: ``30`` (seconds)
The upper bound on how long any compression should take to run. Prevents
dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_.
:Default: ``10``
The amount of time (in seconds) to cache the modification timestamp of a
file. Disabled by default. Should be smaller than COMPRESS_REBUILD_TIMEOUT_
:Default: ``False``
Boolean that decides if compression should also be done outside of the
request/response loop -- independent from user requests. This allows to
pre-compress CSS and JavaScript files and works just like the automatic
compression with the ``{% compress %}`` tag.
To compress the files "offline" and update the offline cache you have
to use the ``compress`` management command, e.g. during deployment.
In case you don't use the ``compressor`` management command ``compressor``
will automatically fallback to the automatic compression.
It'll will look in the templates that can be found with the template
loader you specify in ``TEMPLATE_LOADERS`` for ``{% compress %}`` blocks
and use COMPRESS_OFFLINE_CONTEXT_ to render its content. So if you use
any variables inside the ``{% compress %}`` blocks, make sure to list
all values you require in COMPRESS_OFFLINE_CONTEXT_.
The result of running the ``compress`` management command will be saved
in the cache as defined in COMPRESS_CACHE_BACKEND_ for the number of
seconds defined in COMPRESS_OFFLINE_TIMEOUT_.
:Default: ``31536000`` (1 year in seconds)
The period of time with which the ``compress`` management command stores
the pre-compressed the contents of ``{% compress %}`` template tags in
the cache.
:Default: ``{'MEDIA_URL': settings.MEDIA_URL}``
The context to be used by the ``compress`` management command when rendering
the contents of ``{% compress %}`` template tags and saving the result in the
offline cache. It's similar to a template context and should be used if a
variable is used in the blocks, e.g.:
.. code-block:: django
{% load compress %}
{% compress js %}
<script src="{{ path_to_files }}js/one.js" type="text/javascript" charset="utf-8"></script>
{% endcompress %}
Since this template requires a variable (``path_to_files``) you need to
specify this in your settings before using the ``compress`` management
'path_to_files': '/static/js/',
If not specified the COMPRESS_OFFLINE_CONTEXT will fall back to contain
the commonly used setting to refer to saved files ``MEDIA_URL``.
For forward compatibility ``compressor`` will also add the ``STATIC_URL``
setting (added in Django 1.3) to the COMPRESS_OFFLINE_CONTEXT_ if it's set.
* BeautifulSoup_ (for the default ``compressor.parser.BeautifulSoupParser``)
pip install BeautifulSoup
* lxml_ (for the optional ``compressor.parser.LxmlParser``, requires libxml2_)
STATIC_DEPS=true pip install lxml
.. _BeautifulSoup:
.. _lxml:
.. _libxml2:
Jump to Line
Something went wrong with that request. Please try again.