/docs/ref/contrib/staticfiles.txt

  1===================
  2The staticfiles app
  3===================
  4
  5.. module:: django.contrib.staticfiles
  6   :synopsis: An app for handling static files.
  7
  8.. versionadded:: 1.3
  9
 10``django.contrib.staticfiles`` collects static files from each of your
 11applications (and any other places you specify) into a single location that
 12can easily be served in production.
 13
 14.. seealso::
 15
 16    For an introduction to the static files app and some usage examples, see
 17    :doc:`/howto/static-files`.
 18
 19.. _staticfiles-settings:
 20
 21Settings
 22========
 23
 24.. highlight:: python
 25
 26.. note::
 27
 28    The following settings control the behavior of the staticfiles app.
 29
 30.. setting:: STATICFILES_DIRS
 31
 32STATICFILES_DIRS
 33----------------
 34
 35Default: ``[]``
 36
 37This setting defines the additional locations the staticfiles app will traverse
 38if the :class:`FileSystemFinder` finder is enabled, e.g. if you use the
 39:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
 40static file serving view.
 41
 42This should be set to a list or tuple of strings that contain full paths to
 43your additional files directory(ies) e.g.::
 44
 45    STATICFILES_DIRS = (
 46        "/home/special.polls.com/polls/static",
 47        "/home/polls.com/polls/static",
 48        "/opt/webfiles/common",
 49    )
 50
 51Prefixes (optional)
 52"""""""""""""""""""
 53
 54In case you want to refer to files in one of the locations with an additional
 55namespace, you can **optionally** provide a prefix as ``(prefix, path)``
 56tuples, e.g.::
 57
 58    STATICFILES_DIRS = (
 59        # ...
 60        ("downloads", "/opt/webfiles/stats"),
 61    )
 62
 63Example:
 64
 65Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
 66:djadmin:`collectstatic` management command would collect the "stats" files
 67in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
 68
 69This would allow you to refer to the local file
 70``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
 71``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.::
 72
 73    <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
 74
 75.. setting:: STATICFILES_STORAGE
 76
 77STATICFILES_STORAGE
 78-------------------
 79
 80Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
 81
 82The file storage engine to use when collecting static files with the
 83:djadmin:`collectstatic` management command.
 84
 85For an example, see :ref:`staticfiles-from-cdn`.
 86
 87.. setting:: STATICFILES_FINDERS
 88
 89STATICFILES_FINDERS
 90-------------------
 91
 92Default::
 93
 94    ("django.contrib.staticfiles.finders.FileSystemFinder",
 95     "django.contrib.staticfiles.finders.AppDirectoriesFinder")
 96
 97The list of finder backends that know how to find static files in
 98various locations.
 99
100The default will find files stored in the :setting:`STATICFILES_DIRS` setting
101(using :class:`django.contrib.staticfiles.finders.FileSystemFinder`) and in a
102``static`` subdirectory of each app (using
103:class:`django.contrib.staticfiles.finders.AppDirectoriesFinder`)
104
105One finder is disabled by default:
106:class:`django.contrib.staticfiles.finders.DefaultStorageFinder`. If added to
107your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
108the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
109setting.
110
111.. note::
112
113    When using the :class:`AppDirectoriesFinder` finder, make sure your apps
114    can be found by staticfiles. Simply add the app to the
115    :setting:`INSTALLED_APPS` setting of your site.
116
117Static file finders are currently considered a private interface, and this
118interface is thus undocumented.
119
120Management Commands
121===================
122
123.. highlight:: console
124
125``django.contrib.staticfiles`` exposes three management commands.
126
127collectstatic
128-------------
129
130.. django-admin:: collectstatic
131
132Collects the static files into :setting:`STATIC_ROOT`.
133
134Duplicate file names are by default resolved in a similar way to how template
135resolution works: the file that is first found in one of the specified
136locations will be used. If you're confused, the :djadmin:`findstatic` command
137can help show you which files are found.
138
139Files are searched by using the :setting:`enabled finders
140<STATICFILES_FINDERS>`. The default is to look in all locations defined in
141:setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps
142specified by the :setting:`INSTALLED_APPS` setting.
143
144Some commonly used options are:
145
146``--noinput``
147    Do NOT prompt the user for input of any kind.
148
149``-i PATTERN`` or ``--ignore=PATTERN``
150    Ignore files or directories matching this glob-style pattern. Use multiple
151    times to ignore more.
152
153``-n`` or ``--dry-run``
154    Do everything except modify the filesystem.
155
156``-l`` or ``--link``
157    Create a symbolic link to each file instead of copying.
158
159``--no-default-ignore``
160    Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'``
161    and ``'*~'``.
162
163For a full list of options, refer to the commands own help by running::
164
165   $ python manage.py collectstatic --help
166
167findstatic
168----------
169
170.. django-admin:: findstatic
171
172Searches for one or more relative paths with the enabled finders.
173
174For example::
175
176   $ python manage.py findstatic css/base.css admin/js/core.js
177   /home/special.polls.com/core/static/css/base.css
178   /home/polls.com/core/static/css/base.css
179   /home/polls.com/src/django/contrib/admin/media/js/core.js
180
181By default, all matching locations are found. To only return the first match
182for each relative path, use the ``--first`` option::
183
184   $ python manage.py findstatic css/base.css --first
185   /home/special.polls.com/core/static/css/base.css
186
187This is a debugging aid; it'll show you exactly which static file will be
188collected for a given path.
189
190.. _staticfiles-runserver:
191
192runserver
193---------
194
195.. django-admin:: runserver
196
197Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
198is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static
199files and the following new options.
200
201.. django-admin-option:: --nostatic
202
203Use the ``--nostatic`` option to disable serving of static files with the
204:doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is
205only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
206in your project's :setting:`INSTALLED_APPS` setting.
207
208Example usage::
209
210    django-admin.py runserver --nostatic
211
212.. django-admin-option:: --insecure
213
214Use the ``--insecure`` option to force serving of static files with the
215:doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG`
216setting is ``False``. By using this you acknowledge the fact that it's
217**grossly inefficient** and probably **insecure**. This is only intended for
218local development, should **never be used in production** and is only
219available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
220in your project's :setting:`INSTALLED_APPS` setting.
221
222Example usage::
223
224    django-admin.py runserver --insecure
225
226.. currentmodule:: None
227
228Other Helpers
229=============
230
231The ``static`` context processor
232--------------------------------
233
234.. function:: django.core.context_processors.static
235
236This context processor adds the :setting:`STATIC_URL` into each template
237context as the variable ``{{ STATIC_URL }}``. To use it, make sure that
238``'django.core.context_processors.static'`` appears somewhere in your
239:setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
240
241Remember, only templates rendered with :class:`~django.template.RequestContext`
242will have acces to the data provided by this (and any) context processor.
243
244.. templatetag:: get_static_prefix
245
246The ``get_static_prefix`` templatetag
247=====================================
248
249.. highlight:: html+django
250
251If you're not using :class:`~django.template.RequestContext`, or if you need
252more control over exactly where and how :setting:`STATIC_URL` is injected
253into the template, you can use the :ttag:`get_static_prefix` template tag
254instead::
255
256    {% load static %}
257    <img src="{% get_static_prefix %}images/hi.jpg" />
258
259There's also a second form you can use to avoid extra processing if you need
260the value multiple times::
261
262    {% load static %}
263    {% get_static_prefix as STATIC_PREFIX %}
264
265    <img src="{{ STATIC_PREFIX }}images/hi.jpg" />
266    <img src="{{ STATIC_PREFIX }}images/hi2.jpg" />
267
268.. _staticfiles-development-view:
269
270Static file development view
271----------------------------
272
273.. highlight:: python
274
275.. function:: django.contrib.staticfiles.views.serve(request, path)
276
277This view function serves static files in development.
278
279.. warning::
280
281    This view will only work if :setting:`DEBUG` is ``True``.
282
283    That's because this view is **grossly inefficient** and probably
284    **insecure**. This is only intended for local development, and should
285    **never be used in production**.
286
287This view is automatically enabled by :djadmin:`runserver` (with a
288:setting:`DEBUG` setting set to ``True``). To use the view with a different
289local development server, add the following snippet to the end of your
290primary URL configuration::
291
292   from django.conf import settings
293
294   if settings.DEBUG:
295       urlpatterns += patterns('django.contrib.staticfiles.views',
296           url(r'^static/(?P<path>.*)$', 'serve'),
297       )
298
299Note, the beginning of the pattern (``r'^static/'``) should be your
300:setting:`STATIC_URL` setting.
301
302Since this is a bit finicky, there's also a helper function that'll do this for you:
303
304.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns()
305
306This will return the proper URL pattern for serving static files to your
307already defined pattern list. Use it like this::
308
309   from django.contrib.staticfiles.urls import staticfiles_urlpatterns
310
311   # ... the rest of your URLconf here ...
312
313   urlpatterns += staticfiles_urlpatterns()
314
315.. warning::
316
317    This helper function will only work if :setting:`DEBUG` is ``True``
318    and your :setting:`STATIC_URL` setting is neither empty nor a full
319    URL such as ``http://static.example.com/``.