===================
The staticfiles app
===================
.. module:: django.contrib.staticfiles
:synopsis: An app for handling static files.
.. versionadded:: 1.3
``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.
.. seealso::
For an introduction to the static files app and some usage examples, see
:doc:`/howto/static-files`.
.. _staticfiles-settings:
Settings
========
.. highlight:: python
.. note::
The following settings control the behavior of the staticfiles app.
.. setting:: STATICFILES_DIRS
STATICFILES_DIRS
----------------
Default: ``[]``
This setting defines the additional locations the staticfiles app will traverse
if the :class:`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",
)
Prefixes (optional)
"""""""""""""""""""
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">
.. setting:: STATICFILES_STORAGE
STATICFILES_STORAGE
-------------------
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 :ref:`staticfiles-from-cdn`.
.. setting:: STATICFILES_FINDERS
STATICFILES_FINDERS
-------------------
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 :class:`django.contrib.staticfiles.finders.FileSystemFinder`) and in a
``static`` subdirectory of each app (using
:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder`)
One finder is disabled by default:
:class:`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 :class:`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.
Management Commands
===================
.. highlight:: console
``django.contrib.staticfiles`` exposes three management commands.
collectstatic
-------------
.. django-admin:: collectstatic
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:
``--noinput``
Do NOT prompt the user for input of any kind.
``-i PATTERN`` or ``--ignore=PATTERN``
Ignore files or directories matching this glob-style pattern. Use multiple
times to ignore more.
``-n`` or ``--dry-run``
Do everything except modify the filesystem.
``-l`` or ``--link``
Create a symbolic link to each file instead of copying.
``--no-default-ignore``
Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'``
and ``'*~'``.
For a full list of options, refer to the commands own help by running::
$ python manage.py collectstatic --help
findstatic
----------
.. django-admin:: findstatic
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.
.. _staticfiles-runserver:
runserver
---------
.. django-admin:: runserver
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.
.. django-admin-option:: --nostatic
Use the ``--nostatic`` option to disable serving of static files with the
:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is
only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
in your project's :setting:`INSTALLED_APPS` setting.
Example usage::
django-admin.py runserver --nostatic
.. django-admin-option:: --insecure
Use the ``--insecure`` option to force serving of static files with the
:doc:`staticfiles </ref/contrib/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 :doc:`staticfiles </ref/contrib/staticfiles>` app is
in your project's :setting:`INSTALLED_APPS` setting.
Example usage::
django-admin.py runserver --insecure
.. currentmodule:: None
Other Helpers
=============
The ``static`` context processor
--------------------------------
.. function:: django.core.context_processors.static
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 :class:`~django.template.RequestContext`
will have acces to the data provided by this (and any) context processor.
.. templatetag:: get_static_prefix
The ``get_static_prefix`` templatetag
=====================================
.. highlight:: html+django
If you're not using :class:`~django.template.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" />
.. _staticfiles-development-view:
Static file development view
----------------------------
.. highlight:: python
.. function:: django.contrib.staticfiles.views.serve(request, path)
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 beginning 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:
.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns()
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/``.
