staticfiles.txt 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565
  1. =======================
  2. The ``staticfiles`` app
  3. =======================
  4. .. module:: django.contrib.staticfiles
  5. :synopsis: An app for handling static files.
  6. ``django.contrib.staticfiles`` collects static files from each of your
  7. applications (and any other places you specify) into a single location that
  8. can easily be served in production.
  9. .. seealso::
  10. For an introduction to the static files app and some usage examples, see
  11. :doc:`/howto/static-files/index`. For guidelines on deploying static files,
  12. see :doc:`/howto/static-files/deployment`.
  13. .. _staticfiles-settings:
  14. Settings
  15. ========
  16. See :ref:`staticfiles settings <settings-staticfiles>` for details on the
  17. following settings:
  18. * :setting:`STORAGES`
  19. * :setting:`STATIC_ROOT`
  20. * :setting:`STATIC_URL`
  21. * :setting:`STATICFILES_DIRS`
  22. * :setting:`STATICFILES_FINDERS`
  23. Management Commands
  24. ===================
  25. ``django.contrib.staticfiles`` exposes three management commands.
  26. ``collectstatic``
  27. -----------------
  28. .. django-admin:: collectstatic
  29. Collects the static files into :setting:`STATIC_ROOT`.
  30. Duplicate file names are by default resolved in a similar way to how template
  31. resolution works: the file that is first found in one of the specified
  32. locations will be used. If you're confused, the :djadmin:`findstatic` command
  33. can help show you which files are found.
  34. On subsequent ``collectstatic`` runs (if ``STATIC_ROOT`` isn't empty), files
  35. are copied only if they have a modified timestamp greater than the timestamp of
  36. the file in ``STATIC_ROOT``. Therefore if you remove an application from
  37. :setting:`INSTALLED_APPS`, it's a good idea to use the :option:`collectstatic
  38. --clear` option in order to remove stale static files.
  39. Files are searched by using the :setting:`enabled finders
  40. <STATICFILES_FINDERS>`. The default is to look in all locations defined in
  41. :setting:`STATICFILES_DIRS` and in the ``'static'`` directory of apps
  42. specified by the :setting:`INSTALLED_APPS` setting.
  43. The :djadmin:`collectstatic` management command calls the
  44. :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process`
  45. method of the ``staticfiles`` storage backend from :setting:`STORAGES` after
  46. each run and passes a list of paths that have been found by the management
  47. command. It also receives all command line options of :djadmin:`collectstatic`.
  48. This is used by the
  49. :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage` by
  50. default.
  51. By default, collected files receive permissions from
  52. :setting:`FILE_UPLOAD_PERMISSIONS` and collected directories receive permissions
  53. from :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`. If you would like different
  54. permissions for these files and/or directories, you can subclass either of the
  55. :ref:`static files storage classes <staticfiles-storages>` and specify the
  56. ``file_permissions_mode`` and/or ``directory_permissions_mode`` parameters,
  57. respectively. For example::
  58. from django.contrib.staticfiles import storage
  59. class MyStaticFilesStorage(storage.StaticFilesStorage):
  60. def __init__(self, *args, **kwargs):
  61. kwargs["file_permissions_mode"] = 0o640
  62. kwargs["directory_permissions_mode"] = 0o760
  63. super().__init__(*args, **kwargs)
  64. Then set the ``staticfiles`` storage backend in :setting:`STORAGES` setting to
  65. ``'path.to.MyStaticFilesStorage'``.
  66. Some commonly used options are:
  67. .. django-admin-option:: --noinput, --no-input
  68. Do NOT prompt the user for input of any kind.
  69. .. django-admin-option:: --ignore PATTERN, -i PATTERN
  70. Ignore files, directories, or paths matching this glob-style pattern. Use
  71. multiple times to ignore more. When specifying a path, always use forward
  72. slashes, even on Windows.
  73. .. django-admin-option:: --dry-run, -n
  74. Do everything except modify the filesystem.
  75. .. django-admin-option:: --clear, -c
  76. Clear the existing files before trying to copy or link the original file.
  77. .. django-admin-option:: --link, -l
  78. Create a symbolic link to each file instead of copying.
  79. .. django-admin-option:: --no-post-process
  80. Don't call the
  81. :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process`
  82. method of the configured ``staticfiles`` storage backend from
  83. :setting:`STORAGES`.
  84. .. django-admin-option:: --no-default-ignore
  85. Don't ignore the common private glob-style patterns ``'CVS'``, ``'.*'``
  86. and ``'*~'``.
  87. For a full list of options, refer to the commands own help by running:
  88. .. console::
  89. $ python manage.py collectstatic --help
  90. .. _customize-staticfiles-ignore-patterns:
  91. Customizing the ignored pattern list
  92. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93. The default ignored pattern list, ``['CVS', '.*', '*~']``, can be customized in
  94. a more persistent way than providing the ``--ignore`` command option at each
  95. ``collectstatic`` invocation. Provide a custom :class:`~django.apps.AppConfig`
  96. class, override the ``ignore_patterns`` attribute of this class and replace
  97. ``'django.contrib.staticfiles'`` with that class path in your
  98. :setting:`INSTALLED_APPS` setting::
  99. from django.contrib.staticfiles.apps import StaticFilesConfig
  100. class MyStaticFilesConfig(StaticFilesConfig):
  101. ignore_patterns = [...] # your custom ignore list
  102. ``findstatic``
  103. --------------
  104. .. django-admin:: findstatic staticfile [staticfile ...]
  105. Searches for one or more relative paths with the enabled finders.
  106. For example:
  107. .. console::
  108. $ python manage.py findstatic css/base.css admin/js/core.js
  109. Found 'css/base.css' here:
  110. /home/special.polls.com/core/static/css/base.css
  111. /home/polls.com/core/static/css/base.css
  112. Found 'admin/js/core.js' here:
  113. /home/polls.com/src/django/contrib/admin/media/js/core.js
  114. .. django-admin-option:: findstatic --first
  115. By default, all matching locations are found. To only return the first match
  116. for each relative path, use the ``--first`` option:
  117. .. console::
  118. $ python manage.py findstatic css/base.css --first
  119. Found 'css/base.css' here:
  120. /home/special.polls.com/core/static/css/base.css
  121. This is a debugging aid; it'll show you exactly which static file will be
  122. collected for a given path.
  123. By setting the ``--verbosity`` flag to 0, you can suppress the extra output and
  124. just get the path names:
  125. .. console::
  126. $ python manage.py findstatic css/base.css --verbosity 0
  127. /home/special.polls.com/core/static/css/base.css
  128. /home/polls.com/core/static/css/base.css
  129. On the other hand, by setting the ``--verbosity`` flag to 2, you can get all
  130. the directories which were searched:
  131. .. console::
  132. $ python manage.py findstatic css/base.css --verbosity 2
  133. Found 'css/base.css' here:
  134. /home/special.polls.com/core/static/css/base.css
  135. /home/polls.com/core/static/css/base.css
  136. Looking in the following locations:
  137. /home/special.polls.com/core/static
  138. /home/polls.com/core/static
  139. /some/other/path/static
  140. .. _staticfiles-runserver:
  141. ``runserver``
  142. -------------
  143. .. django-admin:: runserver [addrport]
  144. :noindex:
  145. Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
  146. is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static
  147. files. File serving doesn't run through :setting:`MIDDLEWARE`.
  148. The command adds these options:
  149. .. django-admin-option:: --nostatic
  150. Use the ``--nostatic`` option to disable serving of static files with the
  151. :doc:`staticfiles </ref/contrib/staticfiles>` app entirely. This option is
  152. only available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
  153. in your project's :setting:`INSTALLED_APPS` setting.
  154. Example usage:
  155. .. console::
  156. $ django-admin runserver --nostatic
  157. .. django-admin-option:: --insecure
  158. Use the ``--insecure`` option to force serving of static files with the
  159. :doc:`staticfiles </ref/contrib/staticfiles>` app even if the :setting:`DEBUG`
  160. setting is ``False``. By using this you acknowledge the fact that it's
  161. **grossly inefficient** and probably **insecure**. This is only intended for
  162. local development, should **never be used in production** and is only
  163. available if the :doc:`staticfiles </ref/contrib/staticfiles>` app is
  164. in your project's :setting:`INSTALLED_APPS` setting.
  165. ``--insecure`` doesn't work with :class:`~.storage.ManifestStaticFilesStorage`.
  166. Example usage:
  167. .. console::
  168. $ django-admin runserver --insecure
  169. .. _staticfiles-storages:
  170. Storages
  171. ========
  172. ``StaticFilesStorage``
  173. ----------------------
  174. .. class:: storage.StaticFilesStorage
  175. A subclass of the :class:`~django.core.files.storage.FileSystemStorage`
  176. storage backend that uses the :setting:`STATIC_ROOT` setting as the base
  177. file system location and the :setting:`STATIC_URL` setting respectively
  178. as the base URL.
  179. .. method:: storage.StaticFilesStorage.post_process(paths, **options)
  180. If this method is defined on a storage, it's called by the
  181. :djadmin:`collectstatic` management command after each run and gets passed the
  182. local storages and paths of found files as a dictionary, as well as the command
  183. line options. It yields tuples of three values:
  184. ``original_path, processed_path, processed``. The path values are strings and
  185. ``processed`` is a boolean indicating whether or not the value was
  186. post-processed, or an exception if post-processing failed.
  187. The :class:`~django.contrib.staticfiles.storage.ManifestStaticFilesStorage`
  188. uses this behind the scenes to replace the paths with their hashed
  189. counterparts and update the cache appropriately.
  190. ``ManifestStaticFilesStorage``
  191. ------------------------------
  192. .. class:: storage.ManifestStaticFilesStorage
  193. A subclass of the :class:`~django.contrib.staticfiles.storage.StaticFilesStorage`
  194. storage backend which stores the file names it handles by appending the MD5
  195. hash of the file's content to the filename. For example, the file
  196. ``css/styles.css`` would also be saved as ``css/styles.55e7cbb9ba48.css``.
  197. The purpose of this storage is to keep serving the old files in case some
  198. pages still refer to those files, e.g. because they are cached by you or
  199. a 3rd party proxy server. Additionally, it's very helpful if you want to
  200. apply `far future Expires headers`_ to the deployed files to speed up the
  201. load time for subsequent page visits.
  202. The storage backend automatically replaces the paths found in the saved
  203. files matching other saved files with the path of the cached copy (using
  204. the :meth:`~django.contrib.staticfiles.storage.StaticFilesStorage.post_process`
  205. method). The regular expressions used to find those paths
  206. (``django.contrib.staticfiles.storage.HashedFilesMixin.patterns``) cover:
  207. * The `@import`_ rule and `url()`_ statement of `Cascading Style Sheets`_.
  208. * `Source map`_ comments in CSS and JavaScript files.
  209. Subclass ``ManifestStaticFilesStorage`` and set the
  210. ``support_js_module_import_aggregation`` attribute to ``True``, if you want to
  211. use the experimental regular expressions to cover:
  212. * The `modules import`_ in JavaScript.
  213. * The `modules aggregation`_ in JavaScript.
  214. For example, the ``'css/styles.css'`` file with this content:
  215. .. code-block:: css
  216. @import url("../admin/css/base.css");
  217. ...would be replaced by calling the
  218. :meth:`~django.core.files.storage.Storage.url` method of the
  219. ``ManifestStaticFilesStorage`` storage backend, ultimately saving a
  220. ``'css/styles.55e7cbb9ba48.css'`` file with the following content:
  221. .. code-block:: css
  222. @import url("../admin/css/base.27e20196a850.css");
  223. .. admonition:: Usage of the ``integrity`` HTML attribute with local files
  224. When using the optional ``integrity`` attribute within tags like
  225. ``<script>`` or ``<link>``, its value should be calculated based on the
  226. files as they are served, not as stored in the filesystem. This is
  227. particularly important because depending on how static files are collected,
  228. their checksum may have changed (for example when using
  229. :djadmin:`collectstatic`). At the moment, there is no out-of-the-box
  230. tooling available for this.
  231. You can change the location of the manifest file by using a custom
  232. ``ManifestStaticFilesStorage`` subclass that sets the ``manifest_storage``
  233. argument. For example::
  234. from django.conf import settings
  235. from django.contrib.staticfiles.storage import (
  236. ManifestStaticFilesStorage,
  237. StaticFilesStorage,
  238. )
  239. class MyManifestStaticFilesStorage(ManifestStaticFilesStorage):
  240. def __init__(self, *args, **kwargs):
  241. manifest_storage = StaticFilesStorage(location=settings.BASE_DIR)
  242. super().__init__(*args, manifest_storage=manifest_storage, **kwargs)
  243. .. admonition:: References in comments
  244. ``ManifestStaticFilesStorage`` doesn't ignore paths in statements that are
  245. commented out. This :ticket:`may crash on the nonexistent paths <21080>`.
  246. You should check and eventually strip comments.
  247. .. attribute:: storage.ManifestStaticFilesStorage.manifest_hash
  248. This attribute provides a single hash that changes whenever a file in the
  249. manifest changes. This can be useful to communicate to SPAs that the assets on
  250. the server have changed (due to a new deployment).
  251. .. attribute:: storage.ManifestStaticFilesStorage.max_post_process_passes
  252. Since static files might reference other static files that need to have their
  253. paths replaced, multiple passes of replacing paths may be needed until the file
  254. hashes converge. To prevent an infinite loop due to hashes not converging (for
  255. example, if ``'foo.css'`` references ``'bar.css'`` which references
  256. ``'foo.css'``) there is a maximum number of passes before post-processing is
  257. abandoned. In cases with a large number of references, a higher number of
  258. passes might be needed. Increase the maximum number of passes by subclassing
  259. ``ManifestStaticFilesStorage`` and setting the ``max_post_process_passes``
  260. attribute. It defaults to 5.
  261. To enable the ``ManifestStaticFilesStorage`` you have to make sure the
  262. following requirements are met:
  263. * the ``staticfiles`` storage backend in :setting:`STORAGES` setting is set to
  264. ``'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'``
  265. * the :setting:`DEBUG` setting is set to ``False``
  266. * you've collected all your static files by using the
  267. :djadmin:`collectstatic` management command
  268. Since creating the MD5 hash can be a performance burden to your website
  269. during runtime, ``staticfiles`` will automatically store the mapping with
  270. hashed names for all processed files in a file called ``staticfiles.json``.
  271. This happens once when you run the :djadmin:`collectstatic` management
  272. command.
  273. .. attribute:: storage.ManifestStaticFilesStorage.manifest_strict
  274. If a file isn't found in the ``staticfiles.json`` manifest at runtime, a
  275. ``ValueError`` is raised. This behavior can be disabled by subclassing
  276. ``ManifestStaticFilesStorage`` and setting the ``manifest_strict`` attribute to
  277. ``False`` -- nonexistent paths will remain unchanged.
  278. Due to the requirement of running :djadmin:`collectstatic`, this storage
  279. typically shouldn't be used when running tests as ``collectstatic`` isn't run
  280. as part of the normal test setup. During testing, ensure that ``staticfiles``
  281. storage backend in the :setting:`STORAGES` setting is set to something else
  282. like ``'django.contrib.staticfiles.storage.StaticFilesStorage'`` (the default).
  283. .. method:: storage.ManifestStaticFilesStorage.file_hash(name, content=None)
  284. The method that is used when creating the hashed name of a file.
  285. Needs to return a hash for the given file name and content.
  286. By default it calculates a MD5 hash from the content's chunks as
  287. mentioned above. Feel free to override this method to use your own
  288. hashing algorithm.
  289. .. _`far future Expires headers`: https://developer.yahoo.com/performance/rules.html#expires
  290. .. _`@import`: https://www.w3.org/TR/CSS2/cascade.html#at-import
  291. .. _`url()`: https://www.w3.org/TR/CSS2/syndata.html#uri
  292. .. _`Cascading Style Sheets`: https://www.w3.org/Style/CSS/
  293. .. _`source map`: https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/
  294. .. _`modules import`: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#importing_features_into_your_script
  295. .. _`modules aggregation`: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#aggregating_modules
  296. ``ManifestFilesMixin``
  297. ----------------------
  298. .. class:: storage.ManifestFilesMixin
  299. Use this mixin with a custom storage to append the MD5 hash of the file's
  300. content to the filename as :class:`~storage.ManifestStaticFilesStorage` does.
  301. Finders Module
  302. ==============
  303. ``staticfiles`` finders has a ``searched_locations`` attribute which is a list
  304. of directory paths in which the finders searched. Example usage::
  305. from django.contrib.staticfiles import finders
  306. result = finders.find("css/base.css")
  307. searched_locations = finders.searched_locations
  308. Other Helpers
  309. =============
  310. There are a few other helpers outside of the
  311. :mod:`staticfiles <django.contrib.staticfiles>` app to work with static
  312. files:
  313. - The :func:`django.template.context_processors.static` context processor
  314. which adds :setting:`STATIC_URL` to every template context rendered
  315. with :class:`~django.template.RequestContext` contexts.
  316. - The builtin template tag :ttag:`static` which takes a path and urljoins it
  317. with the static prefix :setting:`STATIC_URL`. If
  318. ``django.contrib.staticfiles`` is installed, the tag uses the ``url()``
  319. method of the ``staticfiles`` storage backend from :setting:`STORAGES`
  320. instead.
  321. - The builtin template tag :ttag:`get_static_prefix` which populates a
  322. template variable with the static prefix :setting:`STATIC_URL` to be
  323. used as a variable or directly.
  324. - The similar template tag :ttag:`get_media_prefix` which works like
  325. :ttag:`get_static_prefix` but uses :setting:`MEDIA_URL`.
  326. - The ``staticfiles`` key in :data:`django.core.files.storage.storages`
  327. contains a ready-to-use instance of the staticfiles storage backend.
  328. .. _staticfiles-development-view:
  329. Static file development view
  330. ----------------------------
  331. .. currentmodule:: django.contrib.staticfiles
  332. The static files tools are mostly designed to help with getting static files
  333. successfully deployed into production. This usually means a separate,
  334. dedicated static file server, which is a lot of overhead to mess with when
  335. developing locally. Thus, the ``staticfiles`` app ships with a
  336. **quick and dirty helper view** that you can use to serve files locally in
  337. development.
  338. .. function:: views.serve(request, path)
  339. This view function serves static files in development.
  340. .. warning::
  341. This view will only work if :setting:`DEBUG` is ``True``.
  342. That's because this view is **grossly inefficient** and probably
  343. **insecure**. This is only intended for local development, and should
  344. **never be used in production**.
  345. .. note::
  346. To guess the served files' content types, this view relies on the
  347. :py:mod:`mimetypes` module from the Python standard library, which itself
  348. relies on the underlying platform's map files. If you find that this view
  349. doesn't return proper content types for certain files, it is most likely
  350. that the platform's map files are incorrect or need to be updated. This can
  351. be achieved, for example, by installing or updating the ``mailcap`` package
  352. on a Red Hat distribution, ``mime-support`` on a Debian distribution, or by
  353. editing the keys under ``HKEY_CLASSES_ROOT`` in the Windows registry.
  354. This view is automatically enabled by :djadmin:`runserver` (with a
  355. :setting:`DEBUG` setting set to ``True``). To use the view with a different
  356. local development server, add the following snippet to the end of your
  357. primary URL configuration::
  358. from django.conf import settings
  359. from django.contrib.staticfiles import views
  360. from django.urls import re_path
  361. if settings.DEBUG:
  362. urlpatterns += [
  363. re_path(r"^static/(?P<path>.*)$", views.serve),
  364. ]
  365. Note, the beginning of the pattern (``r'^static/'``) should be your
  366. :setting:`STATIC_URL` setting.
  367. Since this is a bit finicky, there's also a helper function that'll do this for
  368. you:
  369. .. function:: urls.staticfiles_urlpatterns()
  370. This will return the proper URL pattern for serving static files to your
  371. already defined pattern list. Use it like this::
  372. from django.contrib.staticfiles.urls import staticfiles_urlpatterns
  373. # ... the rest of your URLconf here ...
  374. urlpatterns += staticfiles_urlpatterns()
  375. This will inspect your :setting:`STATIC_URL` setting and wire up the view
  376. to serve static files accordingly. Don't forget to set the
  377. :setting:`STATICFILES_DIRS` setting appropriately to let
  378. ``django.contrib.staticfiles`` know where to look for files in addition to
  379. files in app directories.
  380. .. warning::
  381. This helper function will only work if :setting:`DEBUG` is ``True``
  382. and your :setting:`STATIC_URL` setting is neither empty nor a full
  383. URL such as ``http://static.example.com/``.
  384. That's because this view is **grossly inefficient** and probably
  385. **insecure**. This is only intended for local development, and should
  386. **never be used in production**.
  387. Specialized test case to support 'live testing'
  388. -----------------------------------------------
  389. .. class:: testing.StaticLiveServerTestCase
  390. This unittest TestCase subclass extends :class:`django.test.LiveServerTestCase`.
  391. Just like its parent, you can use it to write tests that involve running the
  392. code under test and consuming it with testing tools through HTTP (e.g. Selenium,
  393. PhantomJS, etc.), because of which it's needed that the static assets are also
  394. published.
  395. But given the fact that it makes use of the
  396. :func:`django.contrib.staticfiles.views.serve` view described above, it can
  397. transparently overlay at test execution-time the assets provided by the
  398. ``staticfiles`` finders. This means you don't need to run
  399. :djadmin:`collectstatic` before or as a part of your tests setup.