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 olderMEDIA_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 olderMEDIA_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 (seeEnvironment.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, theauto_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
inEnvironment.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 insidedirectory
. - 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 forassets.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' ]