=================== The staticfiles app =================== .. module:: django.contrib.staticfiles :synopsis: An app for handling static files. .. versionadded:: 1.3 ``django.contrib.staticfiles`` collects media 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 The following settings control the behavior of the static files app. Only :setting:`STATICFILES_ROOT` is required, but you'll probably also need to configure :setting:`STATICFILES_URL` as well. .. setting:: STATICFILES_ROOT STATICFILES_ROOT ---------------- Default: ``''`` (Empty string) The absolute path to the directory that holds static files:: STATICFILES_ROOT = "/home/example.com/static/" This is a **required setting** unless you've overridden :setting:`STATICFILES_STORAGE` and are using a custom storage backend. .. setting:: STATICFILES_URL STATICFILES_URL --------------- Default: ``'/static/'`` The URL that handles the files served from :setting:`STATICFILES_ROOT`, e.g.:: STATICFILES_URL = '/site_media/static/' ... or perhaps:: STATICFILES_URL = 'http://media.exmaple.com/' This should **always** have a trailing slash. .. 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. It should be defined as a sequence of ``(prefix, path)`` tuples, e.g.:: STATICFILES_DIRS = ( ('', '/home/special.polls.com/polls/media'), ('', '/home/polls.com/polls/media'), ('common', '/opt/webfiles/common'), ) .. 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 Django's app loading mechanism. Simply include a ``models`` module (an empty ``models.py`` file suffices) and 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 two management commands. collectstatic ------------- .. django-admin:: collectstatic Collects the static files into :setting:`STATICFILES_ROOT`. Duplicate file names are resolved in a similar way to how template resolution works: files from apps later in :setting:`INSTALLED_APPS` overwrite those from earlier apps, and files from storage directories later in :setting:`STATICFILES_DIRS` overwrite those from earlier. If you're confused, the :djadmin:`findstatic` command can help show you where Files are searched by using the :ref:`enabled finders `. The default is to look in all locations defined in :ref:`staticfiles-dirs` and in the ``media`` 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/media/css/base.css /home/polls.com/core/media/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/media/css/base.css This is a debugging aid; it'll show you exactly which static file will be collected for a given path. Other Helpers ============= The ``media`` context processor ------------------------------- .. function:: django.contrib.staticfiles.context_processors.staticfiles This context processor adds the :setting:`STATICFILES_URL` into each template context as the variable ``{{ STATICFILES_URL }}``. To use it, make sure that ``'django.contrib.staticfiles.context_processors.staticfiles'`` 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_staticfiles_prefix The ``get_staticfiles_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:`STATICFILES_URL` is injected into the template, you can use the :ttag:`get_staticfiles_prefix` template tag instead:: {% load staticfiles %} There's also a second form you can use to avoid extra processing if you need the value multiple times:: {% load staticfiles %} {% get_staticfiles_prefix as STATIC_PREFIX %} .. _staticfiles-development-view: Static file development view ---------------------------- .. highlight:: python .. function:: django.contrib.staticfiles.views.serve(request, path) This view function serves static media in 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**. To use the view, 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.*)$', 'serve'), ) Note, the begin of the pattern (``r'^static/'``) should be your :setting:`STATICFILES_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()