Settings

There are a bunch of values which you can define in your Django settings module to modify the behaviour of webassets.

Note

This document places those values inside the django_assets.settings module. This is irrelevant. To change the values, you need to define them in your project’s global settings.

django_assets.settings.ASSETS_ROOT

The base directory to which all paths will be relative to, unless load_paths are given, in which case this will only serve as the output directory.

In the url space, it is mapped to urls.

By default, STATIC_ROOT will be used for this, or the older MEDIA_ROOT setting.

django_assets.settings.ASSETS_URL

The url prefix used to construct urls for files in directory.

To define url spaces for other directories, see url_mapping.

By default, STATIC_URL will be used for this, or the older MEDIA_URL setting.

django_assets.settings.ASSETS_DEBUG

Enable/disable debug mode. Possible values are:

False

Production mode. Bundles will be merged and filters applied.

True

Enable debug mode. Bundles will output their individual source files.

“merge”

Merge the source files, but do not apply filters.

django_assets.settings.ASSETS_AUTO_BUILD

Controls whether bundles should be automatically built, and rebuilt, when required (if set to True), or whether they must be built manually be the user, for example via a management command.

This is a good setting to have enabled during debugging, and can be very convenient for low-traffic sites in production as well. However, there is a cost in checking whether the source files have changed, so if you care about performance, or if your build process takes very long, then you may want to disable this.

By default automatic building is enabled.

django_assets.settings.ASSETS_URL_EXPIRE

If you send your assets to the client using a far future expires header (to minimize the 304 responses your server has to send), you need to make sure that assets will be reloaded by the browser when they change.

If this is set to True, then the Bundle URLs generated by webassets will have their version (see Environment.versions) appended as a querystring.

An alternative approach would be to use the %(version)s placeholder in the bundle output file.

The default behavior (indicated by a None value) is to add an expiry querystring if the bundle does not use a version placeholder.

django_assets.settings.ASSETS_VERSIONS

Defines what should be used as a Bundle version.

A bundle’s version is what is appended to URLs when the url_expire option is enabled, and the version can be part of a Bundle’s output filename by use of the %(version)s placeholder.

Valid values are:

timestamp

The version is determined by looking at the mtime of a bundle’s output file.

hash (default)

The version is a hash over the output file’s content.

False, None

Functionality that requires a version is disabled. This includes the url_expire option, the auto_build option, and support for the %(version)s placeholder.

Any custom version implementation.

django_assets.settings.ASSETS_MANIFEST

A manifest persists information about the versions bundles are at.

The Manifest plays a role only if you insert the bundle version in your output filenames, or append the version as a querystring to the url (via the url_expire option). It serves two purposes:

• Without a manifest, it may be impossible to determine the version at runtime. In a deployed app, the media files may be stored on a different server entirely, and be inaccessible from the application code. The manifest, if shipped with your application, is what still allows to construct the proper URLs.

• Even if it were possible to determine the version at runtime without a manifest, it may be a costly process, and using a manifest may give you better performance. If you use a hash-based version for example, this hash would need to be recalculated every time a new process is started.

Valid values are:

"cache" (default)

The cache is used to remember version information. This is useful to avoid recalculating the version hash.

"file:{path}"

Stores version information in a file at {path}. If not path is given, the manifest will be stored as .webassets-manifest in Environment.directory.

"json:{path}"

Same as “file:{path}”, but uses JSON to store the information.

False, None

No manifest is used.

Any custom manifest implementation.

django_assets.settings.ASSETS_CACHE

Controls the behavior of the cache. The cache will speed up rebuilding of your bundles, by caching individual filter results. This can be particularly useful while developing, if your bundles would otherwise take a long time to rebuild.

Possible values are:

False

Do not use the cache.

True (default)

Cache using default location, a .webassets-cache folder inside directory.

custom path

Use the given directory as the cache directory.

django_assets.settings.ASSETS_CACHE_FILE_MODE

Controls the mode of files created in the cache. The default mode is 0600. Follows standard unix mode. Possible values are any unix mode, e.g.:

0660

Enable the group read+write bits

0666

Enable world read+write bits

django_assets.settings.ASSETS_JINJA2_EXTENSIONS

This is needed in some cases when you want to use django-assets with the Jinja 2 template system. It should be a list of extensions you are using with Jinja 2, using which it should be possible to construct a Jinja 2 environment which can parse your templates. For more information, see Jinja2 support.

django_assets.settings.ASSETS_MODULES

django-assets will automatically look for assets.py files in each application, where you can register your bundles. If you want additional modules to be loaded, you can define this setting. It expects a list of importable modules:

ASSETS_MODULES = [
    'myproject.assets'
]