django.contrib.staticfiles collects static files from each of your applications (and any other places you specify) into a single location that can easily be served in production.
See also
For an introduction to the static files app and some usage examples, see Managing static files.
Note
The following settings control the behavior of the staticfiles app.
Default: []
This setting defines the additional locations the staticfiles app will traverse if the FileSystemFinder finder is enabled, e.g. if you use the :djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the static file serving view.
This should be set to a list or tuple of strings that contain full paths to your additional files directory(ies) e.g.:
STATICFILES_DIRS = (
"/home/special.polls.com/polls/static",
"/home/polls.com/polls/static",
"/opt/webfiles/common",
)
In case you want to refer to files in one of the locations with an additional namespace, you can optionally provide a prefix as (prefix, path) tuples, e.g.:
STATICFILES_DIRS = (
# ...
("downloads", "/opt/webfiles/stats"),
)
Example:
Assuming you have :setting:`STATIC_URL` set '/static/', the :djadmin:`collectstatic` management command would collect the "stats" files in a 'downloads' subdirectory of :setting:`STATIC_ROOT`.
This would allow you to refer to the local file '/opt/webfiles/stats/polls_20101022.tar.gz' with '/static/downloads/polls_20101022.tar.gz' in your templates, e.g.:
<a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
Default: 'django.contrib.staticfiles.storage.StaticFilesStorage'
The file storage engine to use when collecting static files with the :djadmin:`collectstatic` management command.
For an example, see Serving static files from a cloud service or CDN.
Default:
("django.contrib.staticfiles.finders.FileSystemFinder",
"django.contrib.staticfiles.finders.AppDirectoriesFinder")
The list of finder backends that know how to find static files in various locations.
The default will find files stored in the :setting:`STATICFILES_DIRS` setting (using django.contrib.staticfiles.finders.FileSystemFinder) and in a static subdirectory of each app (using django.contrib.staticfiles.finders.AppDirectoriesFinder)
One finder is disabled by default: django.contrib.staticfiles.finders.DefaultStorageFinder. If added to your :setting:`STATICFILES_FINDERS` setting, it will look for static files in the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE` setting.
Note
When using the AppDirectoriesFinder finder, make sure your apps can be found by staticfiles. Simply add the app to the :setting:`INSTALLED_APPS` setting of your site.
Static file finders are currently considered a private interface, and this interface is thus undocumented.
django.contrib.staticfiles exposes three management commands.
Collects the static files into :setting:`STATIC_ROOT`.
Duplicate file names are by default resolved in a similar way to how template resolution works: the file that is first found in one of the specified locations will be used. If you're confused, the :djadmin:`findstatic` command can help show you which files are found.
Files are searched by using the :setting:`enabled finders <STATICFILES_FINDERS>`. The default is to look in all locations defined in :setting:`STATICFILES_DIRS` and in the 'static' directory of apps specified by the :setting:`INSTALLED_APPS` setting.
Some commonly used options are:
For a full list of options, refer to the commands own help by running:
$ python manage.py collectstatic --help
Searches for one or more relative paths with the enabled finders.
For example:
$ python manage.py findstatic css/base.css admin/js/core.js
/home/special.polls.com/core/static/css/base.css
/home/polls.com/core/static/css/base.css
/home/polls.com/src/django/contrib/admin/media/js/core.js
By default, all matching locations are found. To only return the first match for each relative path, use the --first option:
$ python manage.py findstatic css/base.css --first
/home/special.polls.com/core/static/css/base.css
This is a debugging aid; it'll show you exactly which static file will be collected for a given path.
Overrides the core :djadmin:`runserver` command if the staticfiles app is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static files and the following new options.
Use the --nostatic option to disable serving of static files with the staticfiles app entirely. This option is only available if the staticfiles app is in your project's :setting:`INSTALLED_APPS` setting.
Example usage:
django-admin.py runserver --nostatic
Use the --insecure option to force serving of static files with the staticfiles app even if the :setting:`DEBUG` setting is False. By using this you acknowledge the fact that it's grossly inefficient and probably insecure. This is only intended for local development, should never be used in production and is only available if the staticfiles app is in your project's :setting:`INSTALLED_APPS` setting.
Example usage:
django-admin.py runserver --insecure
This context processor adds the :setting:`STATIC_URL` into each template context as the variable {{ STATIC_URL }}. To use it, make sure that 'django.core.context_processors.static' appears somewhere in your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
Remember, only templates rendered with RequestContext will have acces to the data provided by this (and any) context processor.
If you're not using RequestContext, or if you need more control over exactly where and how :setting:`STATIC_URL` is injected into the template, you can use the :ttag:`get_static_prefix` template tag instead:
{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" />
There's also a second form you can use to avoid extra processing if you need the value multiple times:
{% load static %}
{% get_static_prefix as STATIC_PREFIX %}
<img src="{{ STATIC_PREFIX }}images/hi.jpg" />
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" />
This view function serves static files in development.
Warning
This view will only work if :setting:`DEBUG` is True.
That's because this view is grossly inefficient and probably insecure. This is only intended for local development, and should never be used in production.
This view is automatically enabled by :djadmin:`runserver` (with a :setting:`DEBUG` setting set to True). To use the view with a different local development server, add the following snippet to the end of your primary URL configuration:
from django.conf import settings
if settings.DEBUG:
urlpatterns += patterns('django.contrib.staticfiles.views',
url(r'^static/(?P<path>.*)$', 'serve'),
)
Note, the begin of the pattern (r'^static/') should be your :setting:`STATIC_URL` setting.
Since this is a bit finicky, there's also a helper function that'll do this for you:
This will return the proper URL pattern for serving static files to your already defined pattern list. Use it like this:
from django.contrib.staticfiles.urls import staticfiles_urlpatterns
# ... the rest of your URLconf here ...
urlpatterns += staticfiles_urlpatterns()
Warning
This helper function will only work if :setting:`DEBUG` is True and your :setting:`STATIC_URL` setting is neither empty nor a full URL such as http://static.example.com/.
Mar 31, 2011