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/awesome.8dd1a2872443.js" charset="utf-8"></script>

django.conf.settings.COMPRESS_URL¶

Default:: STATIC_URL

Controls the URL that linked files will be read from and compressed files will be written to.

django.conf.settings.COMPRESS_ROOT¶

Default:: STATIC_ROOT

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.

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_FILTERS¶

Default:: {'css': ['compressor.filters.css_default.CssAbsoluteFilter', 'compressor.filters.cssmin.rCSSMinFilter'], 'js': ['compressor.filters.jsmin.rJSMinFilter']}

A mapping of resource kinds to the list of filters to apply. The key is used to refer to this resource type in templates when using the {% compress [resource_kind] %} template tag. The value is a list of filters to apply in the given order for that resource.

This library currently includes filters for CSS and Javascript.

CSS Filters

default:

['compressor.filters.css_default.CssAbsoluteFilter', 'compressor.filters.cssmin.rCSSMinFilter']

A list of filters that will be applied to CSS.

Possible options for CSS filters are (including their settings):
- compressor.filters.css_default.CssAbsoluteFilter
  
  A filter that normalizes the URLs used in url() CSS statements. This is necessary since the output css files produced by Django Compressor are in a different location than the source files and relative paths might have become invalid. The filter also appends a hash as query string to the normalized URLs to help with cache busting.
  
  django.conf.settings.COMPRESS_CSS_HASHING_METHOD¶
  
  The method to use when calculating the query string. Either None, 'mtime' (default) or 'content'. Use the None if you want to completely disable that feature, and the 'content' in case you’re using multiple servers to serve your content.
- compressor.filters.css_default.CssRelativeFilter
  
  An alternative to CssAbsoluteFilter. It uses a relative instead of an absolute path to prefix URLs. Specifically, the prefix will be '../' * (N + 1) where N is the depth of settings.COMPRESS_OUTPUT_DIR folder (i.e. 1 for 'CACHE', or 2``for ``CACHE/data etc). This can be useful if you don’t want to hard-code COMPRESS_URL into CSS code.
- 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.yuglify.YUglifyCSSFilter
  
  A filter that passes the CSS content to the yUglify compressor.
  
  django.conf.settings.COMPRESS_YUGLIFY_BINARY¶
  
  The yUglify compressor filesystem path.
  
  django.conf.settings.COMPRESS_YUGLIFY_CSS_ARGUMENTS¶
  
  The arguments passed to the compressor. Defaults to –terminal.
- compressor.filters.cssmin.CSSCompressorFilter
  
  A filter that uses Yury Selivanov’s Python port of the YUI CSS compression algorithm csscompressor.
- compressor.filters.cssmin.rCSSMinFilter
  
  A filter that uses the cssmin implementation rCSSmin to compress CSS (installed by default).
- compressor.filters.cleancss.CleanCSSFilter
  
  A filter that passes the CSS content to the clean-css tool.
  
  django.conf.settings.COMPRESS_CLEAN_CSS_BINARY¶
  
  The clean-css binary filesystem path.
  
  django.conf.settings.COMPRESS_CLEAN_CSS_ARGUMENTS¶
  
  The arguments passed to clean-css.
- 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.
Javascript Filters

Default:

['compressor.filters.jsmin.rJSMinFilter']

A list of filters that will be applied to javascript.

Possible options are:
- compressor.filters.jsmin.rJSMinFilter
  
  A filter that uses the jsmin implementation rJSmin to compress JavaScript code (installed by default).
- compressor.filters.jsmin.CalmjsFilter
  
  A filter that uses the jsmin implementation Calmjs 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.yuglify.YUglifyJSFilter
  
  A filter that passes the JavaScript code to the yUglify compressor.
  
  django.conf.settings.COMPRESS_YUGLIFY_BINARY
  
  The yUglify compressor filesystem path.
  
  django.conf.settings.COMPRESS_YUGLIFY_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 or filter specified as the second item:

mimetype
The mimetype of the file or inline code that should be compiled.
command_or_filter
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.

Alternatively, you may provide the fully qualified class name of a filter you wish to use as a precompiler.

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}'),
    ('text/stylus', 'stylus < {infile} > {outfile}'),
    ('text/foobar', 'path.to.MyPrecompilerFilter'),
)

Note

Depending on the implementation, some precompilers might not support outputting to something else than stdout, so you’ll need to omit the {outfile} parameter when working with those. For instance, if you are using the Ruby version of lessc, you’ll need to set up the precompiler like this:

('text/less', 'lessc {infile}'),

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/output.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/output.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 some additional storage backends:

'compressor.storage.GzipCompressorFileStorage'

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

A subclass of the default storage backend, which will additionally create *.br files of each of the compressed files. It is using the maximum level of compression (11) so compression speed will be low.

django.conf.settings.COMPRESS_STORAGE_ALIAS¶

Default:: 'compressor'

The alias into Django’s STORAGES setting that will be used to save compressed files.

If directly set by the user in STORAGES, Compressor will use this storage, otherwise it otherwise will set a default storage, given by COMPRESS_STORAGE.

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 Optional Dependencies for more info about the packages you need for each parser.

Caching settings¶

django.conf.settings.COMPRESS_CACHE_BACKEND¶

Default:: "default"

The cache to use by Django Compressor. Must be a cache alias specified in your CACHES 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. Should be smaller than COMPRESS_REBUILD_TIMEOUT and COMPRESS_MINT_DELAY.

django.conf.settings.COMPRESS_CACHEABLE_PRECOMPILERS¶

Default:: ()

An iterable of precompiler mimetypes as defined in COMPRESS_PRECOMPILERS for which the compiler output can be cached based solely on the contents of the input file. This lets Django Compressor avoid recompiling unchanged files. Caching is appropriate for compilers such as CoffeeScript where files are compiled one-to-one, but not for compilers such as SASS that have an import mechanism for including one file from another. If caching is enabled for such a compiler, Django Compressor will not know to recompile files when a file they import is modified.

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.

django.conf.settings.COMPRESS_CACHE_KEY_FUNCTION¶

Default:: 'compressor.cache.simple_cachekey'

The function to use when generating the cache key. The function must take one argument which is the partial key based on the source’s hex digest. It must return the full key as a string.

Offline settings¶

django.conf.settings.COMPRESS_OFFLINE¶

Default:: False

Boolean that decides if compression should be done outside of the request/response loop. See Offline Compression for details.

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:: {'STATIC_URL': settings.STATIC_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.

Note

It is also possible to perform offline compression for multiple contexts by providing a list or tuple of dictionaries, or by providing a dotted string pointing to a generator function.

This makes it easier to generate contexts dynamically for situations where a user might be able to select a different theme in their user profile, or be served different stylesheets based on other criteria.

An example of multiple offline contexts by providing a list or tuple:

# project/settings.py:
COMPRESS_OFFLINE_CONTEXT = [
    {'THEME': 'plain', 'STATIC_URL': STATIC_URL},
    {'THEME': 'fancy', 'STATIC_URL': STATIC_URL},
    # ...
]

An example of multiple offline contexts generated dynamically:

# project/settings.py:
COMPRESS_OFFLINE_CONTEXT = 'project.module.offline_context'

# project/module.py:
from django.conf import settings
def offline_context():
    from project.models import Company
    for theme in set(Company.objects.values_list('theme', flat=True)):
        yield {'THEME': theme, 'STATIC_URL': settings.STATIC_URL}

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.

django.conf.settings.COMPRESS_OFFLINE_MANIFEST_STORAGE¶

Default:: compressor.storage.OfflineManifestFileStorage

The dotted path to a Django Storage backend to be used to save the offline manifest.

By default, the file configured with COMPRESS_OFFLINE_MANIFEST will be stored into COMPRESS_OUTPUT_DIR.

An example to output the manifest into the project’s root directory:

# project/settings.py:
COMPRESS_OFFLINE_MANIFEST_STORAGE = 'project.module.PrivateOfflineManifestFileStorage'

# project/module.py:
from compressor.storage import OfflineManifestFileStorage
from django.conf import settings
class PrivateOfflineManifestFileStorage(OfflineManifestFileStorage):
    def __init__(self, *args, **kwargs):
        super().__init__(settings.BASE_DIR, None, *args, **kwargs)

django.conf.settings.COMPRESS_OFFLINE_MANIFEST_STORAGE_ALIAS¶

Default:: 'compressor-offine'

The alias into Django’s STORAGES setting that will be used to save compressed files.

If directly set by the user in STORAGES, Compressor will use this storage, otherwise it otherwise will set a default storage, given by COMPRESS_OFFLINE_MANIFEST_STORAGE.

Settings¶

Base settings¶

Backend settings¶

Caching settings¶

Offline settings¶

Django Compressor

Navigation

Related Topics