Debian Codegraph @

docs/howto/static-files/index.txt

raw
1 =========================================================
2 How to manage static files (e.g. images, JavaScript, CSS)
3 =========================================================
4
5 Websites generally need to serve additional files such as images, JavaScript,
6 or CSS. In Django, we refer to these files as "static files". Django provides
7 :mod:`django.contrib.staticfiles` to help you manage them.
8
9 This page describes how you can serve these static files.
10
11 Configuring static files
12 ========================
13
14 #. Make sure that ``django.contrib.staticfiles`` is included in your
15 :setting:`INSTALLED_APPS`.
16
17 #. In your settings file, define :setting:`STATIC_URL`, for example::
18
19 STATIC_URL = "static/"
20
21 #. In your templates, use the :ttag:`static` template tag to build the URL for
22 the given relative path using the configured ``staticfiles``
23 :setting:`STORAGES` alias.
24
25 .. _staticfiles-in-templates:
26
27 .. code-block:: html+django
28
29 {% load static %}
30 <img src="{% static 'my_app/example.jpg' %}" alt="My image">
31
32 #. Store your static files in a folder called ``static`` in your app. For
33 example ``my_app/static/my_app/example.jpg``.
34
35 .. admonition:: Serving the files
36
37 In addition to these configuration steps, you'll also need to actually
38 serve the static files.
39
40 During development, if you use :mod:`django.contrib.staticfiles`, this will
41 be done automatically by :djadmin:`runserver` when :setting:`DEBUG` is set
42 to ``True`` (see :func:`django.contrib.staticfiles.views.serve`).
43
44 This method is **grossly inefficient** and probably **insecure**,
45 so it is **unsuitable for production**.
46
47 See :doc:`/howto/static-files/deployment` for proper strategies to serve
48 static files in production environments.
49
50 Your project will probably also have static assets that aren't tied to a
51 particular app. In addition to using a ``static/`` directory inside your apps,
52 you can define a list of directories (:setting:`STATICFILES_DIRS`) in your
53 settings file where Django will also look for static files. For example::
54
55 STATICFILES_DIRS = [
56 BASE_DIR / "static",
57 "/var/www/static/",
58 ]
59
60 See the documentation for the :setting:`STATICFILES_FINDERS` setting for
61 details on how ``staticfiles`` finds your files.
62
63 .. admonition:: Static file namespacing
64
65 Now we *might* be able to get away with putting our static files directly
66 in ``my_app/static/`` (rather than creating another ``my_app``
67 subdirectory), but it would actually be a bad idea. Django will use the
68 first static file it finds whose name matches, and if you had a static file
69 with the same name in a *different* application, Django would be unable to
70 distinguish between them. We need to be able to point Django at the right
71 one, and the best way to ensure this is by *namespacing* them. That is,
72 by putting those static files inside *another* directory named for the
73 application itself.
74
75 You can namespace static assets in :setting:`STATICFILES_DIRS` by
76 specifying :ref:`prefixes <staticfiles-dirs-prefixes>`.
77
78 .. _serving-static-files-in-development:
79
80 Serving static files during development
81 =======================================
82
83 If you use :mod:`django.contrib.staticfiles` as explained above,
84 :djadmin:`runserver` will do this automatically when :setting:`DEBUG` is set
85 to ``True``. If you don't have ``django.contrib.staticfiles`` in
86 :setting:`INSTALLED_APPS`, you can still manually serve static files using the
87 :func:`django.views.static.serve` view.
88
89 This is not suitable for production use! For some common deployment
90 strategies, see :doc:`/howto/static-files/deployment`.
91
92 For example, if your :setting:`STATIC_URL` is defined as ``static/``, you can
93 do this by adding the following snippet to your ``urls.py``::
94
95 from django.conf import settings
96 from django.conf.urls.static import static
97
98 urlpatterns = [
99 # ... the rest of your URLconf goes here ...
100 ] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
101
102 .. note::
103
104 This helper function works only in debug mode and only if
105 the given prefix is local (e.g. ``static/``) and not a URL (e.g.
106 ``http://static.example.com/``).
107
108 Also this helper function only serves the actual :setting:`STATIC_ROOT`
109 folder; it doesn't perform static files discovery like
110 :mod:`django.contrib.staticfiles`.
111
112 Finally, static files are served via a wrapper at the WSGI application
113 layer. As a consequence, static files requests do not pass through the
114 normal :doc:`middleware chain </topics/http/middleware>`.
115
116 .. _serving-uploaded-files-in-development:
117
118 Serving files uploaded by a user during development
119 ===================================================
120
121 During development, you can serve user-uploaded media files from
122 :setting:`MEDIA_ROOT` using the :func:`django.views.static.serve` view.
123
124 This is not suitable for production use! For some common deployment
125 strategies, see :doc:`/howto/static-files/deployment`.
126
127 For example, if your :setting:`MEDIA_URL` is defined as ``media/``, you can do
128 this by adding the following snippet to your :setting:`ROOT_URLCONF`::
129
130 from django.conf import settings
131 from django.conf.urls.static import static
132
133 urlpatterns = [
134 # ... the rest of your URLconf goes here ...
135 ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
136
137 .. note::
138
139 This helper function works only in debug mode and only if
140 the given prefix is local (e.g. ``media/``) and not a URL (e.g.
141 ``http://media.example.com/``).
142
143 .. _staticfiles-testing-support:
144
145 Testing
146 =======
147
148 When running tests that use actual HTTP requests instead of the built-in
149 testing client (i.e. when using the built-in :class:`LiveServerTestCase
150 <django.test.LiveServerTestCase>`) the static assets need to be served along
151 the rest of the content so the test environment reproduces the real one as
152 faithfully as possible, but ``LiveServerTestCase`` has only very basic static
153 file-serving functionality: It doesn't know about the finders feature of the
154 ``staticfiles`` application and assumes the static content has already been
155 collected under :setting:`STATIC_ROOT`.
156
157 Because of this, ``staticfiles`` ships its own
158 :class:`django.contrib.staticfiles.testing.StaticLiveServerTestCase`, a subclass
159 of the built-in one that has the ability to transparently serve all the assets
160 during execution of these tests in a way very similar to what we get at
161 development time with ``DEBUG = True``, i.e. without having to collect them
162 using :djadmin:`collectstatic` first.
163
164 Deployment
165 ==========
166
167 :mod:`django.contrib.staticfiles` provides a convenience management command
168 for gathering static files in a single directory so you can serve them easily.
169
170 #. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd
171 like to serve these files, for example::
172
173 STATIC_ROOT = "/var/www/example.com/static/"
174
175 #. Run the :djadmin:`collectstatic` management command:
176
177 .. code-block:: shell
178
179 $ python manage.py collectstatic
180
181 This will copy all files from your static folders into the
182 :setting:`STATIC_ROOT` directory.
183
184 #. Use a web server of your choice to serve the
185 files. :doc:`/howto/static-files/deployment` covers some common deployment
186 strategies for static files.
187
188 Learn more
189 ==========
190
191 This document has covered the basics and some common usage patterns. For
192 complete details on all the settings, commands, template tags, and other pieces
193 included in :mod:`django.contrib.staticfiles`, see :doc:`the staticfiles
194 reference </ref/contrib/staticfiles>`.