Settings

Django Compressor has a number of settings that control its behavior. They’ve been given sensible defaults.

Base settings

django.conf.settings.COMPRESS_ENABLED
Default:the opposite of DEBUG

Boolean that decides if compression will happen. To test compression when DEBUG is True COMPRESS_ENABLED must also be set to True.

When COMPRESS_ENABLED is False the input will be rendered without any compression except for code with a mimetype matching one listed in the COMPRESS_PRECOMPILERS setting. These matching files are still passed to the precompiler before rendering.

An example for some javascript and coffeescript.

{% load compress %}

{% compress js %}
<script type="text/javascript" src="/static/js/site-base.js" />
<script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
{% endcompress %}

With COMPRESS_ENABLED set to False this would give you something like this:

<script type="text/javascript" src="/static/js/site-base.js"></script>
<script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script>
django.conf.settings.COMPRESS_URL
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).

django.conf.settings.COMPRESS_ROOT
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 compressor.storage.CompressorFileStorage.

Note

This setting defaults to MEDIA_ROOT in case STATIC_ROOT is not given, e.g. on older Django versions (< 1.3).

django.conf.settings.COMPRESS_OUTPUT_DIR
Default:'CACHE'

Controls the directory inside COMPRESS_ROOT that compressed files will be written to.

Backend settings

django.conf.settings.COMPRESS_CSS_FILTERS
Default:['compressor.filters.css_default.CssAbsoluteFilter']

A list of filters that will be applied to CSS.

Possible options are (including their settings):

  • compressor.filters.css_default.CssAbsoluteFilter

    A filter that normalizes the URLs used in url() CSS statements.

    django.conf.settings.COMPRESS_CSS_HASHING_METHOD

    The method to use when calculating the hash to append to processed URLs. Either 'mtime' (default) or 'content'. Use the latter in case you’re using multiple server to serve your static files.

  • compressor.filters.csstidy.CSSTidyFilter

    A filter that passes the CSS content to the CSSTidy tool.

    django.conf.settings.COMPRESS_CSSTIDY_BINARY

    The CSSTidy binary filesystem path.

    django.conf.settings.COMPRESS_CSSTIDY_ARGUMENTS

    The arguments passed to CSSTidy.

  • compressor.filters.datauri.CssDataUriFilter

    A filter for embedding media as data: URIs in the CSS.

    django.conf.settings.COMPRESS_DATA_URI_MAX_SIZE

    Only files that are smaller than this in bytes value will be embedded.

  • compressor.filters.yui.YUICSSFilter

    A filter that passes the CSS content to the YUI compressor.

    django.conf.settings.COMPRESS_YUI_BINARY

    The YUI compressor filesystem path. Make sure to also prepend this setting with java -jar if you use that kind of distribution.

    django.conf.settings.COMPRESS_YUI_CSS_ARGUMENTS

    The arguments passed to the compressor.

  • compressor.filters.cssmin.CSSMinFilter

    A filter that uses Zachary Voase’s Python port of the YUI CSS compression algorithm cssmin.

  • compressor.filters.template.TemplateFilter

    A filter that renders the CSS content with Django templating system.

    django.conf.settings.COMPRESS_TEMPLATE_FILTER_CONTEXT

    The context to render your css files with.

django.conf.settings.COMPRESS_JS_FILTERS
Default:['compressor.filters.jsmin.JSMinFilter']

A list of filters that will be applied to javascript.

Possible options are:

  • compressor.filters.jsmin.JSMinFilter

    A filter that uses the jsmin implementation rJSmin to compress JavaScript code.

  • compressor.filters.jsmin.SlimItFilter

    A filter that uses the jsmin implementation Slim It to compress JavaScript code.

  • compressor.filters.closure.ClosureCompilerFilter

    A filter that uses Google Closure compiler.

    django.conf.settings.COMPRESS_CLOSURE_COMPILER_BINARY

    The Closure compiler filesystem path. Make sure to also prepend this setting with java -jar if you use that kind of distribution.

    django.conf.settings.COMPRESS_CLOSURE_COMPILER_ARGUMENTS

    The arguments passed to the compiler.

  • compressor.filters.yui.YUIJSFilter

    A filter that passes the JavaScript code to the YUI compressor.

    django.conf.settings.COMPRESS_YUI_BINARY

    The YUI compressor filesystem path.

    django.conf.settings.COMPRESS_YUI_JS_ARGUMENTS

    The arguments passed to the compressor.

  • compressor.filters.template.TemplateFilter

    A filter that renders the JavaScript code with Django templating system.

    django.conf.settings.COMPRESS_TEMPLATE_FILTER_CONTEXT

    The context to render your JavaScript code with.

django.conf.settings.COMPRESS_PRECOMPILERS
Default:()

An iterable of two-tuples whose first item is the mimetype of the files or hunks you want to compile with the command specified as the second item:

  1. mimetype

    The mimetype of the file or inline code should that should be compiled.

  2. command

    The command to call on each of the files. Modern Python string formatting will be provided for the two placeholders {infile} and {outfile} whose existence in the command string also triggers the actual creation of those temporary files. If not given in the command string, Django Compressor will use stdin and stdout respectively instead.

Example:

COMPRESS_PRECOMPILERS = (
    ('text/coffeescript', 'coffee --compile --stdio'),
    ('text/less', 'lessc {infile} {outfile}'),
    ('text/x-sass', 'sass {infile} {outfile}'),
    ('text/x-scss', 'sass --scss {infile} {outfile}'),
)

Note

The lessc compiler will have different parameters if installed with Ruby Gems and not npm.

With that setting (and CoffeeScript installed), you could add the following code to your templates:

{% load compress %}

{% compress js %}
<script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
<script type="text/coffeescript" charset="utf-8">
# Functions:
square = (x) -> x * x
</script>
{% endcompress %}

This would give you something like this:

<script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script>

The same works for less, too:

{% load compress %}

{% compress css %}
<link type="text/less" rel="stylesheet" href="/static/css/styles.less" charset="utf-8">
<style type="text/less">
@color: #4D926F;

#header {
  color: @color;
}
</style>
{% endcompress %}

Which would be rendered something like:

<link rel="stylesheet" href="/static/CACHE/css/8ccf8d877f18.css" type="text/css" charset="utf-8">
django.conf.settings.COMPRESS_STORAGE
Default:'compressor.storage.CompressorFileStorage'

The dotted path to a Django Storage backend to be used to save the compressed files.

Django Compressor ships with one additional storage backend:

  • 'compressor.storage.GzipCompressorFileStorage'

    A subclass of the default storage backend, which will additionally create *.gz files of each of the compressed files.

django.conf.settings.COMPRESS_PARSER
Default:'compressor.parser.AutoSelectParser'

The backend to use when parsing the JavaScript or Stylesheet files. The AutoSelectParser picks the lxml based parser when available, and falls back to HtmlParser if lxml is not available.

LxmlParser is the fastest available parser, but HtmlParser is not much slower. AutoSelectParser adds a slight overhead, but in most cases it won’t be necessary to change the default parser.

The other two included parsers are considerably slower and should only be used if absolutely necessary.

Warning

In some cases the compressor.parser.HtmlParser parser isn’t able to parse invalid HTML in JavaScript or CSS content. As a workaround you should use one of the more forgiving parsers, e.g. the BeautifulSoupParser.

The backends included in Django Compressor:

  • compressor.parser.AutoSelectParser
  • compressor.parser.LxmlParser
  • compressor.parser.HtmlParser
  • compressor.parser.BeautifulSoupParser
  • compressor.parser.Html5LibParser

See Dependencies for more info about the packages you need for each parser.

Caching settings

django.conf.settings.COMPRESS_CACHE_BACKEND
Default:"default" or CACHE_BACKEND

The backend to use for caching, in case you want to use a different cache backend for Django 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.

django.conf.settings.COMPRESS_REBUILD_TIMEOUT
Default:2592000 (30 days in seconds)

The period of time after which the compressed files are rebuilt even if no file changes are detected.

django.conf.settings.COMPRESS_MINT_DELAY
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.

django.conf.settings.COMPRESS_MTIME_DELAY
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 and COMPRESS_MINT_DELAY.

django.conf.settings.COMPRESS_DEBUG_TOGGLE
Default:None

The name of the GET variable that toggles the debug mode and prevents Django Compressor from performing the actual compression. Only useful for debugging.

Warning

Don’t use this option in production!

An easy convention is to only set it depending on the DEBUG setting:

if DEBUG:
    COMPRESS_DEBUG_TOGGLE = 'whatever'

Note

This only works for pages that are rendered using the RequestContext and the django.core.context_processors.request context processor.

Offline settings

django.conf.settings.COMPRESS_OFFLINE
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.

django.conf.settings.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.

django.conf.settings.COMPRESS_OFFLINE_CONTEXT
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.

If available, the STATIC_URL setting is also added to the context.

django.conf.settings.COMPRESS_OFFLINE_MANIFEST
Default:manifest.json

The name of the file to be used for saving the names of the files compressed offline.